Glossary of Terms
Relevant source files
The following files were used as context for generating this wiki page:
This document provides a glossary of key terms, components, and concepts within the qib13 project. It is derived from the project's source code and documentation, serving as a technical reference for developers. The qib13 system is a reproducible multi-deviation seed recovery tool that transforms a 13-character Generator Code into a 55-character Seed using deterministically generated Encoding Systems.
Sources: README.md:7-11
Core Concepts
This section defines the fundamental concepts that form the basis of the qib13 system architecture.
Master Seed
A string of any length that serves as the root of trust and the primary source of entropy for the deterministic generation of all Encoding Systems. A default master seed is provided, but users are encouraged to supply their own for security.
- Default Value:
xtphkxlzrkleosumdxykzmmhzdtaqdsfbzimlwglctrcezpffqtbfhbiakksgwauprtbhfflulpnrbhghbvpnwqhyozkjgsavudi - Purpose: Ensures that the same set of
Encoding Systemscan be reproduced in different sessions or on different devices.
Sources: README.md:17-20, index.html:200, index.html:902-905
Generator Code
A 13-character string composed of lowercase letters (a-z) that is the input for the encoding process. This code is designed to be simpler and more memorable than the final Seed.
- Length: 13 characters
- Constraint: Must match the regex
^[a-z]+$.
Sources: README.md:22-27, index.html:564-566, index.html:581-583
Seed
A 55-character string composed of lowercase letters (a-z) that is the output of the encoding process. It contains the original Generator Code information along with parity data, which is used for validation during the recovery process.
- Length: 55 characters
- Constraint: Must match the regex
^[a-z]+$.
Sources: README.md:37-40, index.html:597-599, index.html:618-620
Encoding System
A deterministically generated set of parameters used to encode a Generator Code into a Seed and decode a Seed back into a Generator Code. Each system is generated from the Master Seed and includes matrices and a permutation. There are two types: Original System and Deviation System.
Sources: README.md:29-36, index.html:548-555
System Components
The qib13 system is built from several key classes and data structures that manage the encoding and decoding logic.
CryptoSeededRandom Class
A cryptographically secure deterministic random number generator (RNG) that uses HMAC-SHA256 in counter mode. It is initialized with a seed string (derived from the Master Seed) and produces a deterministic sequence of random numbers, which is crucial for generating reproducible Encoding Systems.
The diagram below shows the class structure for the deterministic RNG.
Sources: index.html:432-546, README.md:162-164
EncodingSystem Class
This class encapsulates the logic for a single encoding/decoding system. It holds the system's matrices and permutations and provides methods to generate seeds and recover generator codes.
The diagram below illustrates the structure of the EncodingSystem class.
Sources: index.html:548-701
System Types
Original System
The first and primary encoding system, identified as System 1. It uses a single parity-check matrix (P) of size 42x13. It is generated using the Master Seed with the suffix -original-1.
- Type:
original - Matrices:
{ P: matrixP }(42x13) - Codeword Structure:
[message (13)] + [negated_parity (42)]
Sources: README.md:31-32, index.html:559, index.html:574, index.html:891-899
Deviation System
Additional encoding systems generated to provide redundancy and multiple recovery paths. A deviation system uses two parity-check matrices: P1 (15x13) and P2 (27x13). They are generated using the Master Seed with suffixes like -deviation-2, -deviation-3, etc.
- Type:
deviation - Matrices:
{ P1: matrixP1, P2: matrixP2 }(15x13 and 27x13) - Codeword Structure:
[message (13)] + [negated_parity1 (15)] + [negated_parity2 (27)]
Sources: README.md:33-34, index.html:561, index.html:589, index.html:901-909
Operational Modes & UI
The application UI is divided into tabs, each corresponding to a primary operation.
| Tab Name | Description | Source File |
|---|---|---|
| Generate Systems | Generates a set of Encoding Systems from a Master Seed and a specified number of deviation systems. | index.html:88-99 |
| Generate Seed | Encodes a 13-letter Generator Code into a 55-letter Seed using a selected system. | index.html:101-120 |
| Recover Code | Decodes a 55-letter Seed to find the original Generator Code by trying one or more systems. | index.html:122-141 |
| Batch Test | Runs a series of automated encoding/decoding tests to verify system integrity and performance. | index.html:143-152 |
Seed Generation Flow
The process of generating a Seed from a Generator Code involves several steps, as shown in the flowchart below.
This diagram illustrates the encoding process for both original and deviation systems.
Sources: index.html:557-595, README.md:178-185
Code Recovery Flow
Recovering the Generator Code involves reversing the encoding process. The "Sequential Recovery" mode is the most comprehensive, trying each available system until a valid one is found.
This sequence diagram shows the logic for the sequential recovery mode.
Sources: index.html:1010-1033, README.md:187-194
Key Functions
generateSystems()
Initializes the application by creating the Original System and the requested number of Deviation Systems from the Master Seed.
// index.html:818-822
function generateSystems() {
let masterSeed = document.getElementById('masterSeed').value.trim();
const numSystems = parseInt(document.getElementById('numSystems').value) || 10;
// ...
}
Sources: index.html:818-861
createOriginalSystem(id, seed)
A factory function that uses CryptoSeededRandom to generate the P matrix and permutation for an Original System.
// index.html:891-900
function createOriginalSystem(id, seed) {
const rng = new CryptoSeededRandom(seed + "-original-" + id);
const matrixP = generateRandomMatrix(42, 13, rng);
const permutation = generateRandomPermutation(55, rng);
const inversePermutation = generateInversePermutation(permutation);
return new EncodingSystem(/* ... */);
}
Sources: index.html:891-900
createDeviationSystem(id, seed)
A factory function that uses CryptoSeededRandom to generate the P1 and P2 matrices and permutation for a Deviation System.
// index.html:902-911
function createDeviationSystem(id, seed) {
const rng = new CryptoSeededRandom(seed);
const matrixP1 = generateRandomMatrix(15, 13, rng);
const matrixP2 = generateRandomMatrix(27, 13, rng);
const permutation = generateRandomPermutation(55, rng);
const inversePermutation = generateInversePermutation(permutation);
return new EncodingSystem(/* ... */);
}
Sources: index.html:902-911