The Generator Code

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• index.html

The Generator Code is a core component of the qib13 system. It is a simple, memorable, 13-character string that serves as the primary user input for generating a cryptographically derived 55-character seed. The system is designed to transform this short, user-friendly code into a longer, more complex seed using a deterministic process seeded by a Master Seed. This allows for high reliability and memorability, as users can work with a simple code while the system's security is anchored by the secret Master Seed.

The main purpose of the Generator Code is to be encoded. The reverse process, decoding, allows for the recovery of the original 13-character Generator Code from the 55-character seed, provided the correct Master Seed is used to regenerate the same set of encoding systems. The system explicitly warns against using trivial generator codes like aaaaaaaaaaaaa.

Sources: README.md:10-15, README.md:30-34, README.md:5, index.html:617-620

System Architecture Overview

The Generator Code is the input to a reproducible multi-deviation seed recovery system. The overall architecture revolves around transforming the Generator Code into a Seed and recovering it back. This process is made deterministic and secure by a Master Seed.

This diagram shows the relationship between the main components of the qib13 system.

The Generator Code

Definition and Constraints

The Generator Code is a string with the following properties:

Property	Description	Source Citation
Length	Must be exactly 13 characters.	[index.html:129](https://github.com/genren00/qib13/blob/HEAD/index.html#L129), [README.md:30](https://github.com/genren00/qib13/blob/HEAD/README.md#L30)
Character Set	Must contain only lowercase letters a-z.	[index.html:617](https://github.com/genren00/qib13/blob/HEAD/index.html#L617), [README.md:30](https://github.com/genren00/qib13/blob/HEAD/README.md#L30)
Entropy	Provides approximately 61.1 bits of entropy.	[README.md:50](https://github.com/genren00/qib13/blob/HEAD/README.md#L50)

The system validates the Generator Code before processing. If the code does not meet the length or character set requirements, an error is thrown.

Sources: index.html:617-619

Role in Encoding

The primary function of the Generator Code is to be transformed into a 55-character seed. This process is handled by the generateSeed function in the user interface, which calls the generateSeed method of an EncodingSystem instance.

The following diagram illustrates the encoding process.

This flow is implemented within the EncodingSystem class, specifically in the generateSeedOriginal and generateSeedDeviation methods.

Sources: README.md:102-107, index.html:615-651

Encoding and Recovery

The user interacts with the system via a tabbed interface to generate systems, generate seeds (encode), and recover codes (decode).

Tab	Function
Generate Systems	Uses a Master Seed to create the set of encoding/decoding systems.
Generate Seed	Encodes a 13-character Generator Code into a 55-character seed.
Recover Code	Decodes a 55-character seed to find the original Generator Code.
Batch Test	Runs automated tests to verify the encoding/recovery process.

Sources: index.html:70-74

Seed Generation (Encoding)

When generating a seed from a Generator Code, the user can select one of several modes:

Mode	Description
Original Mode	Uses the first system (System 1) generated from the Master Seed.
Deviation Mode	Uses the second system (System 2).
Random System	Selects a random system from all available systems.
Specific System	Allows the user to specify an exact system index to use for encoding.

Sources: index.html:132-136, index.html:874-893

Code Recovery (Decoding)

When recovering a Generator Code from a seed, the system attempts to reverse the process. The key is that the parity check must pass.

The sequence diagram below shows the process for "Sequential Recovery", where the system tries every available EncodingSystem until one successfully decodes the seed.

This logic is implemented in the recoverGeneratorCode JavaScript function, which iterates through the allSystems array.

Sources: index.html:916-943

Core Classes and Logic

The entire process is managed by a few key JavaScript classes and functions.

EncodingSystem Class

This class encapsulates the logic for a single encoding/decoding system, including its matrices and permutations.

This class diagram shows the structure of the EncodingSystem and its helper CryptoSeededRandom.

Deterministic RNG

The reproducibility of the system depends on a cryptographically secure deterministic random number generator, CryptoSeedenRandom. It uses an HMAC-SHA256 implementation in counter mode. This ensures that the same Master Seed always produces the exact same matrices and permutations for all encoding systems.

The RNG is initialized with a seed string derived from the Master Seed. For example, the original system uses a seed like masterSeed + "-original-1", and deviation systems use seeds like masterSeed + "-deviation-N".

Sources: index.html:188-200, index.html:435-442, index.html:817-820, index.html:828-832

Matrix and Permutation Generation

The CryptoSeededRandom instance is used to generate the core components of each EncodingSystem.

• generateRandomMatrix(rows, cols, rng): Creates a matrix of a given size with random integer values between 0 and 25.
• generateRandomPermutation(n, rng): Creates a random permutation of n elements using the Fisher-Yates shuffle algorithm, seeded by the RNG.

// From index.html
function generateRandomMatrix(rows, cols, rng) {
    const matrix = [];
    for (let i = 0; i < rows; i++) {
        const row = [];
        for (let j = 0; j < cols; j++) {
            row.push(rng.nextInt(0, 26));
        }
        matrix.push(row);
    }
    return matrix;
}

Sources: index.html:835-845, index.html:847-857, README.md:90-100

Conclusion

The Generator Code is the user-facing entry point to the qib13 encoding system. While simple in its own right (a 13-character string), it is the foundation upon which a complex, deterministic, and reproducible 55-character seed is built. Its security is not in its own entropy but is derived from the secrecy of the Master Seed, which governs the entire encoding and decoding landscape. The system's design successfully separates the concern of usability (a simple Generator Code) from security (a complex Master Seed).

Sources: README.md:120-124, README.md:141-147