Deviation Systems
Relevant source files
The following files were used as context for generating this wiki page:- README.md
- index.html
js/encoding.js(Derived fromindex.html)js/crypto.js(Derived fromindex.html)js/ui.js(Derived fromindex.html)
Deviation Systems are a core feature of the qib13 project, providing a reproducible multi-deviation seed recovery mechanism. They allow for the generation of multiple, distinct encoding systems from a single master seed. This architecture enhances the reliability of recovering a 13-character generator code from its corresponding 55-character seed by providing multiple recovery paths. It also adds a layer of security by increasing the entropy of the overall system.
The system is designed around one "Original" system and a user-configurable number of "Deviation" systems. Each system can encode a generator code into a unique seed and, conversely, attempt to decode a seed to recover the original generator code. This multi-system approach is central to the project's goal of balancing memorability, security, and reliability.
Sources: README.md:5-12, index.html:104-111
Architecture and Generation
The entire set of encoding systems, including the Original and all Deviation Systems, is generated deterministically from a single master seed. This ensures that the same set of systems can be reproduced in any session or on any device, provided the same master seed and number of systems are used.
Sources: README.md:20-22, js/ui.js:833-837
System Generation Flow
The generation process is initiated by the user, who provides a master seed and the desired number of deviation systems. A cryptographically secure random number generator (CryptoSeededRandom), seeded by the master seed, is used to create the components for each system.
The following diagram illustrates the generation flow:
This diagram shows how the master seed is used to deterministically create one original system and N deviation systems, each with unique, randomly generated components.
Sources: index.html:833-876, README.md:32-35
Key Generation Components
| Component | Description | Source Function |
|---|---|---|
| Master Seed | A user-provided string that acts as the root of entropy for all system generation. A default is provided if left empty. | generateSystems() |
| Number of Systems (N) | The number of Deviation Systems to generate, in addition to the one Original System. | generateSystems() |
CryptoSeededRandom | A deterministic RNG based on HMAC-SHA256. It is seeded uniquely for each system to ensure its components are unique but reproducible. | CryptoSeedenRandom class |
createDeviationSystem() | A factory function that orchestrates the creation of a single Deviation System, including its matrices and permutation. | createDeviationSystem() |
Sources: index.html:104-107, 471-475, 960-970, js/ui.js:833-837, js/crypto.js:471-475
A Deviation System is created using a seed derived from the master seed and a unique identifier.
// index.html:960-970
function createDeviationSystem(id, seed) {
const rng = new CryptoSeedenRandom(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(
id,
'deviation',
{ P1: matrixP1, P2: matrixP2 },
permutation,
inversePermutation
);
}
The seed passed to this function is constructed as masterSeed + "-deviation-" + i, ensuring each system is based on the master seed but is unique.
Sources: index.html:863-866, 960-970
Deviation System Structure
A Deviation System is an instance of the EncodingSystem class with its type property set to 'deviation'. It is defined by two parity-check matrices (P1 and P2) and a permutation map.
Sources: index.html:565-571, js/encoding.js:565-571
Class Diagram
The EncodingSystem class encapsulates the logic for both Original and Deviation systems.
This diagram shows the main properties and methods of the EncodingSystem class, which handles all encoding and decoding operations.
Sources: index.html:565-718, js/encoding.js:565-718
Components of a Deviation System
| Property | Type | Description |
|---|---|---|
id | number | A unique identifier for the system (e.g., 2, 3, ...). |
type | string | Always 'deviation' for these systems. |
matrices | object | An object containing the two parity-check matrices: { P1, P2 }. |
matrices.P1 | number[][] | A 15x13 matrix of random integers (0-25). |
matrices.P2 | number[][] | A 27x13 matrix of random integers (0-25). |
permutation | number[] | A 55-element array defining the permutation applied during encoding. |
inversePermutation | number[] | The inverse of the permutation, used for decoding. |
The dimensions of the P1 (15x13) and P2 (27x13) matrices are key differentiators from the Original system, which uses a single 42x13 matrix.
Sources: index.html:962-963, js/encoding.js:962-963
Encoding and Decoding Process
The core functions of a Deviation System are to encode a 13-letter generator code into a 55-letter seed and to recover the code from the seed.
Encoding with a Deviation System
The encoding process involves calculating two separate sets of parity values, concatenating them with the message, and then permuting the result.
The following sequence diagram details the generateSeedDeviation method:
This process creates a 55-character seed composed of the 13-character message, 15 characters of parity from P1, and 27 characters of parity from P2, all shuffled by the system's permutation.
Sources: index.html:621-636, js/encoding.js:621-636
Decoding with a Deviation System
Decoding is the reverse process. It involves applying the inverse permutation and then running two separate parity checks to validate the integrity of the seed and recover the original message.
The recoverGeneratorCodeDeviation method is illustrated below:
A recovery attempt is only successful if both parity checks pass. This two-stage validation is unique to Deviation Systems.
Sources: index.html:670-701, js/encoding.js:670-701
Comparison: Original vs. Deviation Systems
While both system types share the same class structure, their internal parameters and logic differ significantly.
| Feature | Original System | Deviation System |
|---|---|---|
| Type | original | deviation |
| Parity Matrices | One 42x13 matrix (P) | Two matrices: P1 (15x13) and P2 (27x13) |
| Codeword Structure | [message (13)] + [negated_parity (42)] | [message (13)] + [negated_parity1 (15)] + [negated_parity2 (27)] |
| Parity Checks | One check | Two sequential checks |
| RNG Seed Suffix | -original-1 | -deviation-i (where i > 1) |
Sources: README.md:32-35, index.html:950-957, 960-970
Conclusion
Deviation Systems are a powerful extension to the core encoding functionality of qib13. By generating multiple, deterministic, yet distinct systems from a master seed, they provide a robust framework for reliable data recovery. The use of two separate parity checks in each Deviation System offers a different error-detection model compared to the single-check Original System. This multi-system architecture is fundamental to the project's design, enhancing both security through added entropy and reliability through redundant recovery paths.
Sources: README.md:129-132, 144-147