work on docs

README.md

@@ -17,11 +17,11 @@
 
 **The main repository for this software is at https://gitlab.com/beardog/Onionr/**
 
-# Summary
+# About
 
 Onionr is a decentralized, peer-to-peer data storage network, designed to be anonymous and resistant to (meta)data analysis and spam/disruption.
 
-Onionr stores data in independent packages referred to as 'blocks'. The blocks are synced to all other nodes in the network. Blocks and user IDs cannot be easily proven to have been created by particular nodes (only inferred). Even if there is enough evidence to believe a particular node created a block, nodes still operate behind Tor or I2P and as such are not trivially known to be at a particular IP address.
+Onionr stores data in independent packages referred to as 'blocks'. The blocks are synced to all other nodes in the network. Blocks and user IDs cannot be easily proven to have been created by a particular user. Even if there is enough evidence to believe that a specific user created a block, nodes still operate behind Tor or I2P and as such cannot be trivially unmasked.
 
 Users are identified by ed25519 public keys, which can be used to sign blocks or send encrypted data.
 
@@ -36,7 +36,7 @@ The whitepaper (subject to change prior to first alpha release) is available [he
 * [X] 🌐 Fully p2p/decentralized, no trackers or other single points of failure
 * [X] 🔒 End to end encryption of user data
 * [X] 📢 Optional non-encrypted blocks, useful for blog posts or public file sharing
-* [X] 💻 Easy API system for integration to websites
+* [X] 💻 Easy API for integration to websites
 * [X] 🕵️ Metadata analysis resistance and anonymity
 * [X] 📡 Transport agnosticism (no internet required)
 
@@ -54,7 +54,7 @@ Friend/contact manager
 
 <img alt='Encrypted, metadata-masking mail application screenshot' src='docs/onionr-3.png' width=600>
 
-Encrypted, metadata-masking mail application.
+Encrypted, metadata-masking mail application. Perhaps the first distributed mail system to have basic forward secrecy.
 
 # Install and Run on Linux
 

docs/http-api.md

@@ -1,2 +1,50 @@
-HTTP API
+# Onionr HTTP API
-TODO
+
+# About HTTP API
+
+All HTTP interfaces in the Onionr reference client use the [Flask](http://flask.pocoo.org/) web framework with the [gevent](http://www.gevent.org/) WSGI server.
+
+## Client & Public difference
+
+The client API server is a locked down interface intended for authenticated local communication. 
+
+The public API server is available only remotely from Tor & I2P. It is the interface in which peers use to communicate with one another.
+
+# Client API
+
+Please note: endpoints that simply provide static web app files are not documented here.
+
+(Client API docs coming soon)
+
+# Public API
+
+* /
+    - Methods: GET
+    - Returns a basic HTML informational banner describing Onionr.
+* /getblocklist
+    - Methods: GET
+    - URI Parameters:
+        - date: unix epoch timestamp for offset
+    - Returns a list of block hashes stored on the node since an offset (all blocks if no timestamp is specified)
+* /getdata/block-hash
+    - Methods: GET
+    - Returns data for a block based on a provided hash
+* /www/file-path
+    - Methods: GET
+    - Returns file data. Intended for manually sharing file data directly from an Onionr node.
+* /ping
+    - Methods: GET
+    - Returns 'pong!'
+* /pex
+    - Methods: GET
+    - Returns a list of peer addresses reached within recent time
+* /announce
+    - Methods: POST
+    - Accepts form data for 'node' (valid node address) and 'random' which is a nonce when hashed (blake2b_256) in the format `hash(peerAddress+serverAddress+nonce)`, begins with at least 5 zeros.
+    - Returns 200 with 'Success' if no error occurs. If the post is invalid, 'failure' with code 406 is returned.
+* /upload
+    - Methods: POST
+    - Accepts form data for 'block' as a 'file' upload.
+    - Returns 200 with 'success' if no error occurs. If the block cannot be accepted, 'failure' with 400 is returned.
+
+# Direct Connection API

docs/specs/block-spec.md

@@ -2,9 +2,9 @@
 
 # Block Description
 
-Onionr 'Blocks' are the primary means of sharing information in Onionr. Blocks are identified by a single hash value of their entire contents.
+Onionr Blocks are the primary means of sharing information in Onionr. Blocks are identified by a single hash value of their entire contents, using SHA3_256.
 
-They contain a JSON metadata section followed by a line break, with the main data following.
+Blocks contain a JSON metadata section followed by a line break, with the main data section comprising the rest.
 
 In the future, the specification will likely be updated to use flags and MessagePack instead of JSON with english keys.
 

onionr/api.py

@@ -186,7 +186,7 @@ class PublicAPI:
                         powHash = powHash.decode()
                     except AttributeError:
                         pass
-                    if powHash.startswith('0000'):
+                    if powHash.startswith('00000'):
                         newNode = clientAPI._core._utils.bytesToStr(newNode)
                         if clientAPI._core._utils.validateID(newNode) and not newNode in clientAPI._core.onionrInst.communicatorInst.newPeers:
                             clientAPI._core.onionrInst.communicatorInst.newPeers.append(newNode)
@@ -194,6 +194,8 @@ class PublicAPI:
                     else:
                         logger.warn(newNode.decode() + ' failed to meet POW: ' + powHash)
             resp = Response(resp)
+            if resp == 'failure':
+                return resp, 406
             return resp
 
         @app.route('/upload', methods=['post'])