tcoi 0.2.5
A New Form of Decentralised Hashing.
Requires Python: >=3.7

## TABLE OF CONTENTS
- [TCOI: THE CODE OF ISHAQ](#tcoi-the-code-of-ishaq)
  - [1. HASHERS](#1-hashers)
  - [2. HASHFILES](#2-hashfiles)
  - [3. HASHSERVERS](#3-hashservers)
  - [USAGE](#usage)
    - [IN PYTHON](#in-python)
    - [IN RUST](#in-rust)
    - [IN JAVASCRIPT](#in-javascript)
  - [CONCLUSION](#conclusion)
  - [LICENSE](#license)

# TCOI: THE CODE OF ISHAQ

*ABSTRACT:* In this Document, I will go through the structure of a variant of hashing that will introduce Hashfiles, Hashservers and Ishaq Codes, which revolves around generating random codes stored in a file containing key-value pairs, called a Hashfile, linked to their original value, as such will be an HTTP web service called a Hashserver that will host this program, called a Hasher, and users will be able to request Ishaq Codes from the Hashserver, and so will the Hashserver retrieve those codes from the Hashfile and give them back to the user in an HTTP Response.

[[GitHub]](https://github.com/QurashiAkh/tcoi/) - [[PyPI]](https://pypi.org/project/tcoi/) - [[Crates.io]](https://crates.io/crates/tcoi/) - [[npm]](https://www.npmjs.com/package/tcoi/)

## 1. HASHERS

The Hasher is the main program that receives a string value, called a text, and then validate if the text is already assigned a code in the Hashfile or not. If it was, then the Hasher will return the code (i.e. the Ishaq Code) back to the user.

If the text wasn’t found in the Hashfile then the Hasher will generate a random 28-letter sequence of characters and insert `Q-` in the beginning. Such will be the new Ishaq Code for that value, which will be returned to the user and appended to the Hashfile.

Such means that the User will always receive the same Ishaq Code if he has given the same text value.

## 2. HASHFILES

Hashfiles are files named `.hashfile` which will contain the hashes generated by the Hasher in a YAML-like format. The Hashfile must be under complete control by the Hasher, and it should be not be tampered with whatsoever. An Example of what a Hashfile contains is the following:

```yaml
ishaq: Q-vN8HH8ZBnjJZaemFGr.B5Z8qlKBI
random text: Q-MsG4Lf0O9zCZgTqmy21UvtAVKUai
hello: Q-2I6FNiwHvIWuEl2tnW3229N5ZAaY
```

## 3. HASHSERVERS

A Hashserver is an HTTP web service that hosts a Hasher which performs the functionality explained above. A Hashserver is an implementation of decentralised Ishaq Codes, as the use of a Hasher alone isn't practical in most use cases.

Users may send `POST` requests to the Hashserver’s home `/` route and the Response will be a JSON-formatted response that consists of an object containing two values, that are `text` which is the original value requested, and `tcoi` which is the Ishaq Code, which would look similar to this:

```json
{
    "text": "dummy text",
    "tcoi": "Q-dummyishaqcode"
}
```

If the `/` Route gets a `DELETE` Request, which clears the Hashfile and deletes all codes, the HTTP Request would need an `Authorization` Header which contains a Secret Passphrase that permits him to perform that operation. If the `/` Route gets an authorised `GET` request, it will return a list of all the currently generated codes. If the `/` Route gets a usual `GET` request, it'll respond with text saying:

```
TCOI Hashserver @ [Hashserver's IP Address or full Domain]
```

Hashservers are conventionally hosted on the subdomain `hs`, as an example:
```
http://hs.example.com
```

## USAGE

### IN PYTHON

In order to use TCOI, you need to [download it](https://pypi.org/project/tcoi/). You can either fork [the Repository](https://github.com/QurashiAkh/tcoi/) or run:

```
pip install tcoi
```

Now you can import the `tcoi` module in your application and make a `Hasher` Instance, then use it to get `TCOI` codes, clear your hashfile, and more. An Example of a simple TCOI-powered program would be:

```python
from tcoi import Hasher

text = input("Q>>> ").strip()

hasher = Hasher()

result = hasher.get_tcoi(text)

print(f"{result['text']}: {result['tcoi']}")
```

### IN RUST

You can also fork the Repository or add [`tcoi`](https://crates.io/crates/tcoi) to your dependencies:

```
cargo add tcoi
```

Then make an Instance of the `Hasher` Struct and use the `get_tcoi` method to retrieve TCOI codes.

See `rust/examples/main.rs`:
```rust
use std::io::{self, Write};

use tcoi::Hasher;

fn main() {
    let mut input_text = String::new();

    print!("Q>>> ");
    io::stdout().flush().unwrap();

    io::stdin()
        .read_line(&mut input_text)
        .expect("UNEXPECTED INPUT!");

    let text = input_text.trim().to_string();

    let hasher = Hasher {};

    match hasher.get_tcoi(text.clone()) {
        Ok(hashmap) => println!("{}: {}", text, hashmap[&text]),
        Err(_) => println!("ERROR: EMPTY TEXT!"),
    }
}
```

### IN JAVASCRIPT

Install the [`tcoi` library](https://www.npmjs.com/package/tcoi) from `npm` using:

```
npm i tcoi
```

then make an instance of the `Hasher` object and make use of its methods to get TCOI codes.

See `js/example.js`:
```javascript
import { Hasher } from 'tcoi'

const hasher = new Hasher()

const result = await hasher.getTcoi("nice")
console.log(result)

const result2 = await hasher.getTcoi("nice")
console.log(result2)

if (result.tcoi === result2.tcoi) {
    console.log("WORKS!")
} else {
    console.log("SOMETHING GOT MESSED UP..")
}
```

## CONCLUSION

The Code of Ishaq is an alternative form of hashing that aims to implement decentralised hashservers that accomplish the goal needed to validate information.

The Code of Ishaq, however, ought not to be used for large filesize hashing, as such would be inconvenient considering the inefficiency of reuploading a large file back to the Hashserver after downloading it from the source, merely to verify the assigned TCOI for it. The Code of Ishaq is implemented to be used for hashing text messages generally and what goes by that nature.

## LICENSE

TCOI is licensed under the [GNU GPL 3.0](https://www.gnu.org/licenses/gpl-3.0.txt) License.