21 files changed, 498 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a4415af
--- /dev/null
+++ b/README.md
@@ -0,0 +1,10 @@
+# Gradecoin Site
+URL: https://gradecoin.xyz/
+
+Uses [Zola](http://getzola.org/).
+
+```bash
+zola serve --open # for local building & testing
+zola build
+```
+
diff --git a/config.toml b/config.toml
new file mode 100644
index 0000000..070b762
--- /dev/null
+++ b/config.toml
@@ -0,0 +1,28 @@
+# The URL the site will be built for
+base_url = "https://gradecoin.xyz"
+
+theme = "juice"
+
+title = "Gradecoin"
+description = "Mine Your Grades"
+
+# Whether to automatically compile all Sass files in the sass directory
+compile_sass = true
+
+# Whether to build a search index to be used later on by a JavaScript library
+build_search_index = true
+
+[markdown]
+# Whether to do syntax highlighting
+# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
+highlight_code = true
+highlight_theme = "subway-moscow"
+
+[extra]
+# Put all your custom variables here
+juice_logo_name = "Gradecoin"
+juice_logo_path = "gradecoin.png"
+juice_extra_menu = [
+    { title = "why?", link = "https://github.com/zhuowei/nft_ptr#why"}
+]
+
diff --git a/content/JWT.md b/content/JWT.md
new file mode 100644
index 0000000..46da1a2
--- /dev/null
+++ b/content/JWT.md
@@ -0,0 +1,41 @@
++++
+title = "JWT"
+description = "JSON Web Token Documentation"
+weight = 4
++++
+
+> JSON Web Tokens are representations of claims, or authorization proofs that fit into the `Header` of HTTP requests.
+
+# How?
+
+JWTs are used as the [MAC](https://en.wikipedia.org/wiki/Message_authentication_code) of operations that require authorization:
+- block proposal
+- transaction proposal.
+
+They are send alongside the JSON request body in the `Header`;
+
+```html
+Authorization: Bearer aaaaaa.bbbbbb.ccccc
+```
+
+Gradecoin uses 3 fields for the JWTs;
+
+```json
+{
+"tha": "Hash of the payload, check invididual references",
+"iat": "Issued At, Unix Time",
+"exp": "Expiration Time, epoch"
+}
+```
+
+- `tha` is explained in [blocks](@/block_docs.md) and [transactions](@/transaction_docs.md) documentations.
+- `iat` when the JWT was created in [Unix Time](https://en.wikipedia.org/wiki/Unix_time) format
+- `exp` when the JWT will expire & be rejected in [Unix Time](https://en.wikipedia.org/wiki/Unix_time)
+
+# Algorithm
+We are using [RS256](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.1), `RSASSA-PKCS1-v1_5 using SHA-256`. The JWTs you encode with your private RSA key will be decoded using the public key you have authenticated with. You can see how the process works [here](https://jwt.io/).
+
+# References
+- [RFC, the ultimate reference](https://tools.ietf.org/html/rfc7519)
+- [JWT Debugger](https://jwt.io/)
+
diff --git a/content/_index.md b/content/_index.md
new file mode 100644
index 0000000..d0be673
--- /dev/null
+++ b/content/_index.md
@@ -0,0 +1,98 @@
++++
+title = "Gradecoin"
+sort_by = "weight"
++++
+
+# Welcome to Gradecoin!
+
+Blockchains are incredibly simple yet can appear very complicated, we will see how they work and practice programming _production_ cryptography code.
+
+This server is the sandbox for the PA1, it's currently running the Gradecoin application. Gradecoin is the faux currency we will use to simulate a blockchain network. At the end of the simulation, the amount of Gradecoin you hold will be your PA1 grade.
+
+**A quick summary**: authenticate yourself to the system using public key encryption.
+Craft [Transaction](@/transaction_docs.md) proposals and tag them using [JWTs](@/JWT.md).
+When there are enough transactions then you can propose [Blocks](@/block_docs.md) in the same way.
+Blocks need to be _mined_ beforehand using Proof-of-work, or brute force.
+
+Gradecoin offers 3 endpoints at [/register](/register), [/block](/block) and [/transaction](/transaction). You can only send GET requests to /block and /transaction without authorization.
+The server is programmed in [RESTful](https://www.service-architecture.com/articles/web-services/representational_state_transfer_rest.html) architecture, there are no `DELETE`, `PUT` or `UPDATE` operations, though.
+
+Gradecoin uses a Proof-of-work block accepting mechanism. It uses single round [Blake2s](https://www.blake2.net/) hashing which produces 256-bit (64 hexadecimal characters) output. The [target](https://wiki.bitcoinsv.io/index.php/Target) hash is _24 bits_ or _6 hexadecimal characters_ of 0. During testing, I could mine a block on average around 4-6 minutes.
+
+> We're expecting you to use existing tools and implementations. Standards are hard. [Don't roll your own crypto](https://www.reddit.com/r/crypto/comments/2coqsy/dont_roll_your_own/). Feel free to ask questions. Collaborate.
+
+You might ask,
+
+> But if nobody has any Gradecoin then how do we have transactions?
+
+There is a bank! Their public key is `31415926535897932384626433832795028841971693993751058209749445923` and they have some amount of Gradecoin preloaded. It's also the only account that you can send transactions requests _to_ yourself.
+
+# Coinbase
+The first transactions of a block is called the `coinbase`. They are the **author** of the block proposal and if the block is accepted then they get compensated for their efforts with some Gradecoin.
+
+# Public Key Signatures
+Gradecoin uses 2048 bit RSA keypairs.
+
+# Services
+## /register
+- Create your own 2048 bit RSA `keypair`
+- Download `Gradecoin`'s Public Key from [Moodle](https://odtuclass.metu.edu.tr/my/)
+- Encrypt your [JSON](https://www.json.org/json-en.html) wrapped `Public Key`, `Student ID` and one time `passwd` using Gradecoin's Public Key
+- Your public key is now in our database and can be used to sign your JWT's during requests
+- For more information, check the [register](@/register_docs.md) page
+
+## /transaction
+- You can offer a [Transaction](@/transaction_docs.md) with a POST request
+    - The request should have `Authorization`
+    - The request header should be signed by the Public Key of the `by` field in the transaction
+- Fetch the list of `Transaction`s with a GET request
+- For more information, check our [transaction](@/transaction_docs.md) page
+
+## /block
+- Offer a [Block](@/block_docs.md) with a POST request
+    - The request should have `Authorization`
+    - The `transaction_list` of the block should be a subset of pending transactions, available on [/transaction](/transaction)
+- Fetch the last accepted `Block` with a GET request
+- For more information, check our [block](@/block_docs.md) page
+
+    `Authorization`: The request header should have Bearer JWT.Token signed with Student Public Key
+
+## /user
+- Meant to be used in the browser, you can see the current list of users and their balance here
+
+# Questions
+## This all sound complicated!
+- I've drawn inspiration from [actual Bitcoin transactions](https://explorer.bitcoin.com/btc) and [warp](https://github.com/seanmonstar/warp/blob/master/examples/todos.rs). The simplicity of the system is how little interfaces it has.
+- Don't know where to start? Gradecoin uses RESTful API; simple `curl` commands or even your browser will work! [This website can help as well](https://curl.trillworks.com/).
+- [JWT Debugger](https://jwt.io) and the corresponding [RFC](https://tools.ietf.org/html/rfc7519).
+- Remember that you are absolutely encouraged to grab off-the-shelf implementations for every cryptography primitive you will use. You can start by finding a code snippet to generate a RSA keypair?
+- Check out [misc](@/misc_docs.md) for everything else you might be curious about.
+
+## How do you actually earn Gradecoin?
+- Register yourself to at [/register](@/register_docs.md)
+- Create transactions at [/transaction](@/transaction_docs.md)
+- Create blocks to commit transactions at [/block](@/block_docs.md)
+- See how everyone is doing and find people to trade with at [/user](/user)
+
+## I found a bug!
+Thank you! Please [let me know](mailto:yigit@ceng.metu.edu.tr) so we can solve it.
+
+## I hacked the server!
+That wasn't supposed to happen :( I did not place any intentional vulnerabilities to the system so if you cracked something, it was not intended. Please don't abuse it and let me know so I can patch it.
+
+## Submission?
+At the end of the _simulation_, your Gradecoin balance will be your grade. I will also expect a unique client programmed in either;
+- c
+- c++
+- perl
+- rust
+- python
+- random assortment of bash scripts
+
+If your favourite programming language is missing please let me know 🤷?
+
+## Can my friends play?
+Sadly, no. Student's who are enrolled to the class will receive one-time-passwords for authentication.
+
+## How and or Why?
+- [Built](https://xkcd.com/2314/), [with](https://lofi.cafe/) [Rust](https://xkcd.com/2418/)
diff --git a/content/block_docs.md b/content/block_docs.md
new file mode 100644
index 0000000..92880b6
--- /dev/null
+++ b/content/block_docs.md
@@ -0,0 +1,43 @@
++++
+title = "Blocks"
+description = "Block Documentation"
+weight = 10
++++
+
+A block that was proposed to commit Transactions in `transaction_list` to the
+ledger with a nonce that made `hash` valid; 6 zeroes at the left hand side of the
+hash (24 bytes).
+
+We are _mining_ using [blake2s](https://www.blake2.net/) algorithm, which produces 256 bit hashes. Hash/second is roughly {{ exp(num="20x10", exponent="3") }} on my machine, a new block can be mined in around 4-6 minutes.
+
+# Requests
+
+## GET
+A HTTP `GET` request to [/block](/block) endpoint will return the latest mined block.
+
+## POST
+
+A HTTP `POST` request with Authorization using JWT will allow you to propose your own blocks.
+
+# Fields
+```
+transaction_list: [array of Fingerprints]
+nonce: unsigned 32-bit integer
+timestamp: ISO 8601 <date>T<time>
+hash: String
+```
+
+# Mining
+The _mining_ process for the hash involves;
+- Creating a temporary JSON object with `transaction_list`, `timestamp` and `nonce` values
+- Serializing it
+- Calculating blake2s hash of the serialized string
+
+If the resulting hash is valid, then you can create a `Block` JSON object with the found `nonce` and `hash`.
+
+# Hash
+
+```tha``` field in [jwt documentation](/jwt) in fact stands for "The Hash", in the case of a post request for a block, you need to use hash field of the block.
+
+
+[ISO 8601 Reference](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
diff --git a/content/misc_docs.md b/content/misc_docs.md
new file mode 100644
index 0000000..90ea514
--- /dev/null
+++ b/content/misc_docs.md
@@ -0,0 +1,17 @@
++++
+title = "Misc"
+description = "Documentation about everything else"
+weight = 10
++++
+
+We thought it might be good to explain some concepts you might have questions about.
+
+# Fingerprint
+
+## Definition
+
+A fingerprint is a 256 bit 64 character hexadecimal user identifier for users. Fingerprints are used in defining users in [transactions](@/transaction_docs.md) and [blocks](@/block_docs.md).
+
+## Fingerprint Generation
+
+A user's finger print is generated via applying SHA256 sum of the user's public RSA key.
diff --git a/content/register_docs.md b/content/register_docs.md
new file mode 100644
index 0000000..974fe37
--- /dev/null
+++ b/content/register_docs.md
@@ -0,0 +1,54 @@
++++
+title = "Register"
+description = "Register Documentation"
+weight = 3
++++
+
+POST request to `/register` endpoint
+
+Lets a user to authenticate themselves to the system.
+Only people who are enrolled to the class can open Gradecoin accounts.
+This is enforced with your Student ID (e123456) and a one time password you will receive.
+
+# Authentication Process
+
+> The bytes you are sending over the network are all Base64 Encoded
+
+- Gradecoin's Public Key (`gradecoin_public_key`) is listed on our Moodle page and [here](/gradecoin.pub). Download and load it it to your client.
+- Create a JSON object (`P_AR`) with your `metu_id` ("e"+`6 chars`) and `public key` in base64 (PEM) format (`S_PK`) [reference](https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem)
+```json
+{
+    "student_id": "e123456",
+    "passwd": "15 char secret",
+    "public_key": "---BEGIN PUBLIC KEY..."
+}
+```
+
+## Cipher Initialization
+
+> Since we are working with AES-128, both key and IV should be 128 bits (or 16 hexadecimal characters)
+
+- Pick a short temporary key (`k_temp`)
+- Pick a random IV [1](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Initialization_vector_(IV)) [2](https://en.wikipedia.org/wiki/Initialization_vector) (`iv`).
+
+## Encryption
+- Encrypt the serialized string of `P_AR` with 128 bit block [AES](https://en.wikipedia.org/wiki/Initialization_vector) in [CBC](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC) mode with [Pkcs7 padding](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Padding) using the temporary key (`k_temp`), the result is `C_AR`. Encode this with base64.
+- The temporary key you have picked `k_temp` is encrypted using RSA with [OAEP](https://en.wikipedia.org/wiki/Optimal_asymmetric_encryption_padding) padding scheme using SHA-256 with `gradecoin_public_key`, giving us `key_ciphertext`. Encode this with base64.
+- Base64 encode the IV (`iv`) as well.
+
+{% tidbit() %}
+The available tools and libraries might warn you about how using the primitives given above are "hazardous". They are, crypto is hard.
+{% end %}
+
+- The payload JSON object (`auth_request`) can be serialized now:
+
+```json
+{
+    "c": "C_AR",
+    "iv": "iv",
+    "key": "key_ciphertext"
+}
+```
+
+If your authentication process was valid, you will be given access and your public key fingerprint that is your address.
+You can now sign [JWTs](@/JWT.md) to send authorized transaction requests.
diff --git a/content/transaction_docs.md b/content/transaction_docs.md
new file mode 100644
index 0000000..05c1534
--- /dev/null
+++ b/content/transaction_docs.md
@@ -0,0 +1,52 @@
++++
+title = "Transactions"
+description = "Transaction documentation"
+weight = 6
++++
+
+A transaction request between `source` and `target` to move `amount` Gradecoin.
+
+# Requests
+
+## GET
+A HTTP `GET` request to [/transaction](/transaction) endpoint will return the current list of pending transactions.
+
+## POST
+
+A HTTP `POST` request with Authorization using JWT to [/transaction](/transactions) will allow you to propose your own transactions.
+
+# Fields
+```
+by: Fingerprint
+source: Fingerprint
+target: Fingerprint
+amount: unsigned 16 bit integer
+timestamp: ISO 8601 <date>T<time>
+```
+
+# Hash
+
+`tha` field in [jwt documentation](@/JWT.md) in fact stands for "The Hash", in the case of a post request for a transaction, you need the Md5 hash of the serialized JSON representation of transaction. The resulting JSON string should look something like;
+
+```
+{"by":"foo","source":"bar","target":"baz","amount":2,"timestamp":"2021-04-18T21:49:00"}
+```
+
+Or; without any whitespace, separated with `:` and `,`.
+
+# Bank
+
+There is a `bank` account with Fingerprint `31415926535897932384626433832795028841971693993751058209749445923`
+
+{% tidbit() %}
+First 64 digits of Pi
+{% end %}
+
+This is the only account that will let you _withdraw_ from them.
+
+```
+by: this has to be your Fingerprint
+source: this can be either you or the bank
+target: this can be a valid fingerprint or yourself if source is the bank
+...
+```
diff --git a/static/android-chrome-192x192.png b/static/android-chrome-192x192.png
new file mode 100644
index 0000000..023ddbd
--- /dev/null
+++ b/static/android-chrome-192x192.png
diff --git a/static/android-chrome-512x512.png b/static/android-chrome-512x512.png
new file mode 100644
index 0000000..4251933
--- /dev/null
+++ b/static/android-chrome-512x512.png
diff --git a/static/apple-touch-icon.png b/static/apple-touch-icon.png
new file mode 100644
index 0000000..cd8e4c8
--- /dev/null
+++ b/static/apple-touch-icon.png
diff --git a/static/favicon-16x16.png b/static/favicon-16x16.png
new file mode 100644
index 0000000..bd63d34
--- /dev/null
+++ b/static/favicon-16x16.png
diff --git a/static/favicon-32x32.png b/static/favicon-32x32.png
new file mode 100644
index 0000000..e343587
--- /dev/null
+++ b/static/favicon-32x32.png
diff --git a/static/favicon.ico b/static/favicon.ico
new file mode 100644
index 0000000..45d8bfe
--- /dev/null
+++ b/static/favicon.ico
diff --git a/static/gradecoin.png b/static/gradecoin.png
new file mode 100644
index 0000000..eeb670c
--- /dev/null
+++ b/static/gradecoin.png
diff --git a/static/gradecoin.pub b/static/gradecoin.pub
new file mode 100644
index 0000000..ffe2f12
--- /dev/null
+++ b/static/gradecoin.pub
@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyGuqiCPGcguy+Y9TH7Bl
+7XlEsalyqb9bYlzpbV0dnqZ3lPkEPkuOhkN+GcuiV6iXtSwyh7nB+xTRXKJFRUBO
+/jbN8jfcxVwBu0JxjF3v1YRBxbOHhz2A295mbKD9xHQCKxkfYBNkUXxj8gd+GaDv
+QiSW5NdrX/lEkvqfGtdEX1m2+HdcG0+3YW24Xg0znhCwLr+sorLuJaDy9Xa0Uo+D
+PWGC5s001U/BxkCIWJ+eJQCb7Bv+9vXb8BGRK/ecMb/fb6h5O+8fgB64RCHMgcc2
+v+Q/dPt8kHX1OJdMuYUrUJGACppMQY3W6e1HdlRIBcZKL2LMZ2CrIB/2D5LiJhPT
+hQIDAQAB
+-----END PUBLIC KEY-----
diff --git a/static/site.css b/static/site.css
new file mode 100644
index 0000000..6c79aa9
--- /dev/null
+++ b/static/site.css
@@ -0,0 +1,57 @@
+.content blockquote {
+    border-left: #689d6a 8px solid;
+
+}
+.content blockquote.tidbit {
+    border-left: #928f74 8px solid;
+    font-size: 12px;
+    color: #282828;
+}
+
+li p {
+    margin: 2px;
+}
+
+/* OUTER CONTAINER */
+.tcontainer {
+  width: 100%;
+  overflow: hidden; /* Hide scroll bar */
+}
+
+/* MIDDLE CONTAINER */
+.ticker-wrap {
+  width: 100%;
+  padding-left: 100%; /* Push contents to right side of screen */
+  background-color: #eee;
+}
+
+/* INNER CONTAINER */
+@keyframes ticker {
+    0% { transform: translate3d(0, 0, 0); }
+    100% { transform: translate3d(-100%, 0, 0); }
+}
+
+.ticker-move {
+    /* Basically move items from right side of screen to left in infinite loop */
+    display: inline-block;
+    white-space: nowrap;
+    padding-right: 100%;
+    animation-iteration-count: infinite;
+    animation-timing-function: linear;
+    animation-name: ticker;
+    animation-duration: 30s;
+}
+
+.ticker-move:hover{
+    animation-play-state: paused; /* Pause scroll on mouse hover */
+}
+
+/* ITEMS */
+.ticker-item {
+    display: inline-block; /* Lay items in a horizontal line */
+    padding: 0 5px;
+}
+
+.ticker-item::before {
+    content: "  ✑  ";
+}
diff --git a/templates/_variables.html b/templates/_variables.html
new file mode 100644
index 0000000..3fd05b4
--- /dev/null
+++ b/templates/_variables.html
@@ -0,0 +1,15 @@
+<style>
+    :root {
+        /* Primary theme color */
+        --primary-color: #F8D12F;
+        /* Primary theme text color */
+        --primary-text-color: #1E2329;
+        /* Primary theme link color */
+        --primary-link-color: #2F57F7;
+        /* Secondary color: the background body color */
+        --secondary-color: #FAFAFA;
+        --secondary-text-color: #303030;
+        /* Highlight text color of table of content */
+        --toc-highlight-text-color: #d46e13;
+    }
+</style>
diff --git a/templates/index.html b/templates/index.html
new file mode 100644
index 0000000..08e3c8a
--- /dev/null
+++ b/templates/index.html
@@ -0,0 +1,68 @@
+{% extends "juice/templates/index.html" %}
+
+{% block head %}
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css" />
+<link rel="stylesheet" href="/site.css" />
+{% endblock head %}
+
+{% block hero %}
+
+<section class="text-center">
+    <h1 class="heading-text animate__animated animate__jackInTheBox" style="font-size: 50px">
+        Mine your own grades
+    </h1>
+    <h3 class="title-text">
+        <b>Gradecoin</b> is the latest cutting edge blockchain technology agile grading framework that drives organic engagement and other buzzwords, with big data mining search engine optimization
+    </h3>
+    <div>
+    </div>
+</section>
+<img class="hero-image" style="width: 40%" src="{{ get_url(path="gradecoin.png") }}">
+
+<div class="explore-more text"
+     onclick="document.getElementById('features').scrollIntoView({behavior: 'smooth'})">
+    ⇩ Learn How ⇩
+</div>
+
+<style>
+
+.hero section {
+    padding: 0 5rem;
+}
+
+@media screen and (max-width: 768px) {
+    .hero section {
+        padding: 0 2rem;
+    }
+
+    .hero-image {
+        display: none
+    }
+
+}
+footer {
+    color: #8b8b8b;
+}
+</style>
+{% endblock hero %}
+
+{% block content %}
+<div class="tcontainer" id="features">
+    <div class="ticker-wrap">
+        <div class="ticker-move">
+            <div class="ticker-item"><b>News:</b></div>
+            <div class="ticker-item">Gradecoin is in testnet mode, API is not stable, everything might reset at any time.</div>
+            <div class="ticker-item">Transactions are now unique according to their "by" field, sorry for the trouble</div>
+            <div class="ticker-item">Blocks now require 5 transactions in them, during testnet phase</div>
+            <div class="ticker-item">It was possible (and hilarious) to mine a new block with just 1 transaction, it is now fixed</div>
+        </div>
+    </div>
+</div>
+{{ section.content | safe }}
+{% endblock content %}
+
+{% block footer %}
+<footer>
+Built For ⁂ CENG489 ⁂ Introduction to Computer Security
+</footer>
+{% endblock footer %}
diff --git a/templates/shortcodes/exp.html b/templates/shortcodes/exp.html
new file mode 100644
index 0000000..5a37a39
--- /dev/null
+++ b/templates/shortcodes/exp.html
@@ -0,0 +1 @@
+{{ num }}<sup>{{ exponent }}</sup>
diff --git a/templates/shortcodes/tidbit.html b/templates/shortcodes/tidbit.html
new file mode 100644
index 0000000..7023578
--- /dev/null
+++ b/templates/shortcodes/tidbit.html
@@ -0,0 +1,5 @@
+<blockquote class="tidbit">
+    <p>
+    {{ body }}
+    </p>
+</blockquote>