Architectural Overview

Relevant source files

The following files were used as context for generating this wiki page. As the project is primarily a single-file application, logical sections within index.html are treated as distinct sources for citation purposes to provide comprehensive coverage.

• README.md
• index.html (UI Structure)
• index.html (Core Application Logic)
• index.html (EncodingSystem Class)
• index.html (CryptoSeededRandom Class)

The qib13 project is a self-contained, single-page web application designed as a reproducible multi-deviation seed recovery system. Its primary purpose is to transform a short, memorable 13-character "generator code" into a longer 55-character "seed" and allow for the reverse recovery process. The architecture is built around the deterministic generation of multiple unique "Encoding Systems" from a single "Master Seed". This provides both security through the master seed's secrecy and reliability through the redundancy of multiple systems.

The entire application logic, including cryptographic functions, encoding/decoding algorithms, and the user interface, is encapsulated within a single index.html file. This design choice prioritizes offline use and security by minimizing external dependencies. The system's security model relies on the entropy of the master seed, while its usability is enhanced by allowing simple generator codes.

Sources: README.md:10-16, index.html (UI Structure):1-86

Core Components

The system is composed of several key conceptual components that work together to perform the encoding and recovery operations.

Sources: README.md:18-24

Component	Description	Source
Master Seed	A user-provided string that acts as the root of entropy. It is used to deterministically generate all encoding systems. A default value is provided if none is entered.	README.md:26-29 index.html (Core Application Logic):184-186, 882-887
Generator Code	A 13-character lowercase string (a-z) that serves as the input message for encoding.	README.md:31-37 index.html (UI Structure):127
Encoding Systems	A set of deterministically generated algorithms, each defined by unique matrices and permutations. There is one "Original" system and N "Deviation" systems.	README.md:39-47 index.html (EncodingSystem Class):482-490
Seed	The 55-character lowercase string (a-z) output by an encoding system. It contains the generator code's information plus parity data for validation.	README.md:49-51 index.html (UI Structure):148

This diagram illustrates the relationship between the core components.

System Generation

All encoding systems are generated deterministically from the master seed. This process is initiated by the user via the "Generate Systems" or "Use Default Systems" buttons.

The flow for generating systems is as follows:

1. A master seed string is provided by the user or a default is used.
2. An instance of CryptoSeededRandom is created for each system to be generated, using the master seed plus a unique suffix (e.g., -original-1, -deviation-2) to ensure each system's RNG is unique but still deterministic.
3. The createOriginalSystem and createDeviationSystem functions use the seeded RNG to generate random matrices and a random permutation.
4. An EncodingSystem object is instantiated with these generated components and stored in the global allSystems array.

Deterministic Random Number Generation

Cryptographically secure and deterministic random number generation is critical for the reproducibility of the encoding systems. The CryptoSeededRandom class is responsible for this.

Implementation

• Algorithm: It uses an HMAC-SHA256 generator in counter mode. The master seed is used to derive a key for the HMAC function.
• State: The class maintains an internal counter, which is incremented for each block of random bytes generated. The HMAC function is computed over this counter: HMAC-SHA256(key, counter).
• Fallback: A pure JavaScript implementation of SHA-256 and HMAC is included to ensure functionality in environments where the Web Crypto API is not available.
• Output: The nextInt(min, max) method provides uniformly distributed integers in a given range, using rejection sampling to avoid modulo bias.

Sources: index.html (CryptoSeededRandom Class):182-480, README.md:132-134

Class Structure

This diagram shows the key components of the CryptoSeededRandom class.

Encoding and Decoding Engine

The core logic for transforming data between generator codes and seeds resides in the EncodingSystem class.

Class Structure

Each EncodingSystem instance holds the parameters that define its unique transformation.

Encoding Process (generateSeed)

The encoding process converts a 13-letter generator code into a 55-letter seed.

1. The 13-letter code is converted into a vector of 13 numbers (0-25).
2. Parity data is calculated by multiplying the number vector by the system's matrix (or matrices).
3. The parity data is negated (mod 26).
4. A 55-element codeword is formed by concatenating the original message vector and the negated parity vector(s).
5. The system's permutation is applied to the codeword.
6. The resulting permuted vector is converted back to a 55-letter string.

This sequence diagram shows the generateSeed flow for a 'deviation' type system.

Recovery Process (recoverGeneratorCode)

The recovery process attempts to extract the original 13-letter generator code from a 55-letter seed.

1. The 55-letter seed is converted into a vector of 55 numbers.
2. The system's inverse permutation is applied to the vector to restore the original codeword order.
3. The codeword is split into the message part (first 13 numbers) and the parity part(s).
4. The expected parity is recalculated from the message part using the same matrix multiplication as in the encoding step.
5. The recalculated (and negated) parity is compared with the parity extracted from the seed. If they do not match, an error is thrown, indicating the seed is invalid for this specific system.
6. If the parity check passes, the 13-number message is converted back to a letter string and returned.

User Interface Architecture

The application's UI is a single-page interface organized into four main functional tabs.

Sources: index.html (UI Structure):88-94

Tab	ID	Functionality
Generate Systems	generate-tab	Allows the user to generate a new set of encoding systems from a custom or default master seed.
Generate Seed	encode-tab	Encodes a 13-letter generator code into a 55-letter seed using a selected encoding system.
Recover Code	recover-tab	Recovers a generator code from a seed. It can try all systems sequentially or a specific one.
Batch Test	test-tab	Runs an automated test to verify the integrity of the encoding/recovery loop for a random set of codes and systems.

The switchTab JavaScript function handles the visibility of the content for each tab, providing a simple navigation model without page reloads.

Sources: index.html (UI Structure):88-180, index.html (Core Application Logic):981-994

Conclusion

The architecture of qib13 is a clever blend of deterministic cryptographic principles and linear algebra, all packaged into a portable and secure single-file web application. Its strength lies in the deterministic generation of a complex state (multiple encoding systems) from a single, user-controlled secret (the master seed). The separation of concerns between the CryptoSeededRandom class for entropy generation, the EncodingSystem class for algorithmic transformation, and the main application logic for UI interaction creates a modular and understandable, if monolithic, codebase. This design successfully balances the goals of high reliability, user-friendliness, and security for its intended purpose.

Sources: README.md:167-175