Merge pull request #72 from planet-nine-app/issue-54/contributing-gui…

…delines-and-cleanup

documentation

docs/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# How to contribute
+
+I'm of the opinion that contributing should be as easy and inviting as possible. 
+This guide is written with that premise in mind.
+
+The discussion about Sessionless takes place on Discord in the [Open Source Force][osf] server. 
+Follow that link to get an invite. 
+
+Before contributing, I recommend you read through the READMEs and supporting documentation thoroughly.
+
+## Testing
+
+New language implementations should include an example server, which is added to the color tests of the language CLIs (of which only javascript and Rust are currently setup for new languages).
+
+New client implementations should be testable against any of the example servers, and should include an example with some simple UI for doing that test.
+
+Unit tests for implementations are encouraged, but not required since testing an implementation against itself can give false positives.[^1]
+
+## Submitting changes
+
+Please send a with a clear list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). 
+Feel free to give us a heads up on Discord of your impressive contribution.
+
+## Coding conventions
+
+The Sessionless repo is multi-language, and multi-platform so there are no global conventions. 
+Still some concepts are common between implementations.
+
+* Sessionless is small (only 6-8 functions), and should be as flat as possible.
+Try to avoid indirection, and unecessary abstraction.
+
+* Your implementation should match the words of the names of functions, but adopt other conventions of your language, i.e. snake_casing vs camelCasing.
+
+* If your implementation errors, it should log a clear message about why it is erroring.
+
+Thank you for your interest in Sessionless!
+We look forward to seeing what you come up with.
+
+Planet Nine & Open Source Force
+
+[osf]: https://opensourceforce.net

src/cpp/README.md

@@ -1,7 +1,7 @@
 ### Overview
 
 The c++ implementation of Sessionless wraps the c bitcoin-core secp256k1 library.
-It has been tested on Mac, and Linux (and Arduino--coming soon). 
+It has been tested on Mac, Linux, and Arduino. 
 c++ doesn't really have a package manager, so you'll want to include sessionless from git.
 Check the CMakeLists.txt in src/cpp/client/example for instructions on how to do this.
 

src/csharp/Sessionless/README.md

@@ -1,5 +1,9 @@
 # Sessionless
 
+[*Sessionless*](https://www.github.com/planet-nine-app/sessionless) is a multi-language implementation of public-key cryptography.
+It's trying to be like the cordless drill or sewing machine of authentication--a tool everyone can have in their house t
+o help them make things.
+
 This is the C# implementation of the Sessionless protocol--a protocol for providing auth without user data like emails, passwords, or sessions.
 
 

src/javascript/README.md

@@ -0,0 +1,26 @@
+# Sessionless
+
+This folder holds the JavaScript, and TypeScript implementation of Sessionless. 
+There are node, and React Native Expo versions currently.
+The node version should work everywhere you want it to, there's just a need for platform-specific implementations due to how secure things are stored. 
+
+## Usage
+
+### Installation
+
+Currently these are available only in npm, though other registries should come soon. 
+So a standard `npm i sessionless-node` should work for you.
+
+### Methods
+
+Function | What it does
+:--------|:------------|
+`generateKeys(saveKeys?: keys => void, getKeys?: () => Keys)` | Generates a private/public keypair and stores it in the platform's secure storage. Takes an optional `saveKeys` function for platforms that don't have clear-cut secure storage. 
+`getKeys()` | Gets keys from secure storage.
+`sign(message: String)` | Signs a message with the user's private key.
+`verifySignature(message: String, signature: String, publicKey: String)` | Verifies a given signature with a public key.
+`generateUUID()` | Creates a unique UUID for a user.
+`associateKeys(associationMessage: String, primarySignature: String, secondarySignature: String, publicKey: String)` | Associates a secondary's key with the user's primary key.
+`revokeKey(message: String, signature: String, publicKey: String)` | Revokes a gateway's key from the user.
+
+

src/javascript/node/README.md

@@ -1,5 +1,9 @@
 # Sessionless
 
+[*Sessionless*](https://www.github.com/planet-nine-app/sessionless) is a multi-language implementation of public-key cryptography.
+It's trying to be like the cordless drill or sewing machine of authentication--a tool everyone can have in their house t
+o help them make things.
+
 This is the node implementation of the Sessionless protocol--a protocol for providing auth without user data like emails, passwords, or sessions.
 For examples of various server implementations, please see [here][examples].
 

src/python/README.md

@@ -0,0 +1,28 @@
+# Sessionless
+
+This folder holds the Python implementation of Sessionless. 
+There is a Flask example, and a cli as well.
+
+## Usage
+
+### Installation
+
+Currently available in pip.
+`pip install sessionless`
+
+### Methods
+
+* NOTE * These are pseudocode methods. 
+Please check documentation in Pip for the actual method signatures.
+
+Function | What it does
+:--------|:------------|
+`generateKeys(saveKeys?: keys => void, getKeys?: () => Keys)` | Generates a private/public keypair and stores it in the platform's secure storage. Takes an optional `saveKeys` function for platforms that don't have clear-cut secure storage. 
+`getKeys()` | Gets keys from secure storage.
+`sign(message: String)` | Signs a message with the user's private key.
+`verifySignature(message: String, signature: String, publicKey: String)` | Verifies a given signature with a public key.
+`generateUUID()` | Creates a unique UUID for a user.
+`associateKeys(associationMessage: String, primarySignature: String, secondarySignature: String, publicKey: String)` | Associates a secondary's key with the user's primary key.
+`revokeKey(message: String, signature: String, publicKey: String)` | Revokes a gateway's key from the user.
+
+

src/python/package/README.md

@@ -4,6 +4,10 @@
 
 ## About
 
+[*Sessionless*](https://www.github.com/planet-nine-app/sessionless) is a multi-language implementation of public-key cryptography.
+It's trying to be like the cordless drill or sewing machine of authentication--a tool everyone can have in their house t
+o help them make things.
+
 [Sessionless](https://sessionless.org/) is an open-source authentication protocol that uses the cryptography employed by Bitcoin and Ethereum to authenticate messages sent between a client and a server. Within this protocol, you create and store a private key on the client and then use that key to sign messages; the server then verifies those messages via the public key associated with the client. When you verify a message you also certify its provenance. Sessions are wholly unnecessary because no other secret needs to be shared between client and server.
 
 ## Getting Started 

src/rust/README.md

@@ -0,0 +1,22 @@
+# Sessionless
+
+This folder holds the Rust implementation of Sessionless. 
+There is a hyper example, and a cli as well.
+
+## Usage
+
+### Installation
+
+Currently available as a crate.
+`cargo add sessionless`
+
+### Methods
+
+| Function                                                                                              | What it does                                              |
+|:------------------------------------------------------------------------------------------------------|:----------------------------------------------------------|
+| `Sessionless::new()`                                                                                  | Generates new context object with private/public keypair. |
+| `Sessionless::public_key(&self)`                                                                      | Returns the public key.                                   |
+| `Sessionless::private_key(&self)`                                                                     | Returns the private key.                                  |
+| `Sessionless::sign(&self, message: impl AsRef<[u8]>)`                                                 | Signs a message with the user's private key.              |
+| `Sessionless::verify(&self, message: impl AsRef<[u8]>, publicKey: &PublicKey, signature: &Signature)` | Verifies a given signature with a public key.             |
+| `Sessionless::generate_uuid()`                                                                        | Creates a unique UUID for a user.                         |

src/rust/crate/README.md

@@ -1,6 +1,10 @@
 # Sessionless
 
-Rust implementation of the [Sessionless](https://github.com/planet-nine-app/sessionless) protocol.
+[*Sessionless*](https://www.github.com/planet-nine-app/sessionless) is a multi-language implementation of public-key cryptography.
+It's trying to be like the cordless drill or sewing machine of authentication--a tool everyone can have in their house t
+o help them make things.
+
+Rust implementation of the [Sessionless](https://sessionless.org) protocol.
 
 > Sessionless is an authentication protocol that uses the cryptography employed by Bitcoin and Ethereum to authenticate messages sent between a client and a server.
 

src/swift/README.md

@@ -1,5 +1,7 @@
 ### Overview
 
+[PLEASE NOTE I THINK THIS MIGHT BE BROKEN RIGHT NOW. HOPEFULLY I REMEMBER TO REMOVE THIS MESSAGE WHEN I FIX IT]
+
 The Swift implementation of Sessionless is available as a local pod from this repo. 
 I think the new hotness is spm, so I'll likely distribute like that instead, but for now you can just grab the client-ios folder from this repo, and link it in your Podfile.
 See any of the examples' Podfiles for how to do this.