Getting Started

Relevant source files

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

• index.html
• README.md

This document provides a technical overview of the qib13 project, a reproducible multi-deviation seed generation and recovery system. The system is implemented as a single, self-contained HTML file that can be run offline for maximum security. It transforms a simple, memorable 13-character "generator code" into a more complex 55-character "seed" using one of several deterministically generated encoding systems.

The core principle is to enable reliable recovery of the generator code from the seed. This is achieved by generating multiple "deviation" systems from a single "master seed." The security of the system relies on the secrecy of this master seed, which acts as the root of trust and the primary source of entropy for generating the encoding systems.

Sources: README.md:5-13

System Architecture

The qib13 system is built upon four fundamental components that work together to encode and decode information. The entire process is deterministic, meaning the same inputs will always produce the same outputs, which is critical for reproducibility.

Sources: README.md:15-24

Core Components

Component	Description	Source
Master Seed	A user-provided string of any length that deterministically generates all encoding systems. The system's security depends on its secrecy.	README.md:28-31
Generator Code	A 13-character lowercase string (a-z) that serves as the input message to be encoded.	README.md:33-38
Encoding Systems	A set of algorithms generated from the master seed. There is one 'original' system and multiple 'deviation' systems, each capable of encoding the generator code.	README.md:40-48
Seed	The 55-character lowercase string (a-z) output by an encoding system. It contains the generator code and parity information for recovery.	README.md:50-52

The relationship between these components is illustrated below.

This diagram shows how the Master Seed is used to generate multiple Encoding Systems, which in turn encode a Generator Code into a Seed. The recovery process uses the Seed and the same set of Encoding Systems to retrieve the original Generator Code.

Sources: README.md:15-24, index.html:813-827

System Generation

Before any encoding or recovery can occur, the encoding systems must be generated. This process is initiated from the "Generate Systems" tab in the user interface.

Sources: index.html:83-93

Generation Flow

The user provides a masterSeed and the desired number of deviation systems. If no master seed is provided, a hardcoded default is used. The generation process follows these steps:

1. The generateSystems() or useDefaultSystems() function is called.
2. An 'original' system is created using the master seed.
3. A loop runs to create the specified number of 'deviation' systems. Each deviation system is seeded with a combination of the master seed and its index (e.g., masterSeed + "-deviation-2").
4. Each system generation involves creating random matrices and a random permutation using a cryptographically secure deterministic random number generator (CryptoSeededRandom) seeded from the master seed.
5. The generated systems are stored in the global allSystems array.

Sources: index.html:712-780, README.md:40-44

This flowchart illustrates the process of generating the 'original' and 'deviation' encoding systems from a master seed.

Sources: index.html:712-758, index.html:782-811

System Types

Two types of EncodingSystem are generated:

• Original System: The first system, generated with the seed masterSeed + "-original-1". It uses a single parity matrix P of size 42x13.
• Deviation System: Subsequent systems, generated with seeds like masterSeed + "-deviation-2". They use two parity matrices: P1 (15x13) and P2 (27x13).

Sources: index.html:518-525, index.html:538-552, README.md:41-44

Core Logic: The EncodingSystem Class

The EncodingSystem class encapsulates all the logic for encoding a generator code into a seed and recovering it.

Sources: index.html:512-647

This diagram shows the structure of the EncodingSystem class, including its properties and key methods for encoding and recovery.

Sources: index.html:513-520

Seed Generation (Encoding)

Seed generation converts the 13-letter generator code into a 55-letter seed. The process depends on the system type ('original' or 'deviation').

Sources: index.html:522-536, index.html:95-117

Original System Encoding Flow

1. The 13-letter code is converted to a 13-element vector of numbers (0-25).
2. A 42-element parity vector is calculated by multiplying the 42x13 P matrix with the message vector.
3. The parity vector is negated (mod 26).
4. The 13-element message and 42-element negated parity are concatenated to form a 55-element codeword.
5. The codeword is shuffled using the system's permutation map.
6. The resulting 55 numbers are converted back to letters to form the final seed.

Sources: index.html:538-552

Deviation System Encoding Flow

The flow is similar to the original system, but uses two parity matrices.

1. The 13-letter code is converted to a 13-element vector of numbers.
2. A 15-element parity vector (parity1) is calculated using the 15x13 P1 matrix.
3. A 27-element parity vector (parity2) is calculated using the 27x13 P2 matrix.
4. Both parity vectors are negated (mod 26).
5. The 13-element message, 15-element negatedParity1, and 27-element negatedParity2 are concatenated to form a 55-element codeword.
6. The codeword is shuffled using the system's permutation map.
7. The result is converted back to letters.

Sources: index.html:554-572

This diagram visualizes the encoding process for both original and deviation systems.

Code Recovery (Decoding)

Recovery is the reverse of generation, aiming to extract the 13-letter generator code from the 55-letter seed. The UI provides three modes for recovery: sequential, original, and specific.

Sources: index.html:123-133, index.html:902-978

Recovery Flow

1. The 55-letter seed is converted to a 55-element vector of numbers.
2. The inversePermutation is applied to undo the shuffling, yielding the original codeword.
3. The codeword is split into the message part (first 13 elements) and the parity part(s).
4. The expected parity is recalculated from the message part using the system's matrix/matrices.
5. The recalculated (and negated) parity is compared with the parity part from the seed.
6. If they match, the recovery is successful, and the 13-element message is converted back to letters. If not, an error is thrown, and in sequential mode, the next system is tried.

Sources: index.html:574-623

This flowchart shows the decoding process, including the logic for sequential recovery across multiple systems.

Cryptographically Secure RNG

The determinism of the entire qib13 system is guaranteed by a custom seeded random number generator, CryptoSeededRandom. This ensures that the same master seed always produces the exact same set of encoding systems.

Sources: index.html:183-185, README.md:124-125

The implementation uses HMAC-SHA256 in counter mode. It prioritizes the browser's native Web Crypto API for performance and security but includes a pure JavaScript fallback implementation of SHA-256 and HMAC for compatibility with environments where the Web Crypto API is not available.

• CryptoSeededRandom: The main class that takes a seed string.
• _initializeSync(): Initializes the RNG by creating a key from the seed string via SHA-256.
• _generateMoreBytesSync(): Generates a new block of random bytes by computing HMAC-SHA256(key, counter).
• nextInt(min, max): Provides an unbiased random integer in a given range using rejection sampling to avoid modulo bias.

Sources: index.html:383-495

// Matrix generation using the seeded RNG
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:829-839, README.md:129-141

Conclusion

Getting started with qib13 involves three main steps:

1. Generate Systems: Use a secret masterSeed to generate a reproducible set of 'original' and 'deviation' encoding systems.
2. Encode: Select one of the generated systems to transform a simple 13-letter generatorCode into a 55-letter seed.
3. Recover: Use the same masterSeed to regenerate the systems and attempt recovery of the generatorCode from the seed. The sequential recovery mode provides resilience by trying all systems until one succeeds.

The architecture separates the memorable, low-entropy generator code from the high-entropy, secret master seed, providing a balance of usability and security.

Sources: README.md:179-186