Add documentation structure and documentation for general and core, r…

…emove this.dictionary from public access
TogaTech · Oct 17, 2021 · 7683bb1 · 7683bb1
1 parent a8895e3
commit 7683bb1
Show file tree

Hide file tree

Showing 3 changed files with 294 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -1,20 +1,40 @@
 <p align="center">
-  <a href="https://togatech.org/" target="_blank" rel="noopener noreferrer">
-    <img src="https://togatech.org/favicon.png" width="100" alt="TogaTech Logo">
-  </a>
+	<a href="https://togatech.org/" target="_blank" rel="noopener noreferrer">
+		<img src="https://togatech.org/favicon.png" width="100" alt="TogaTech Logo">
+	</a>
 </p>
 
 <h1 align="center">tEnvoy</h1>
 <p align="center">
-  <a href="https://github.com/TogaTech/tEnvoy/actions"><img src="https://img.shields.io/github/workflow/status/TogaTech/tEnvoy/Node.js%20CI" alt="Build Status"></a>
-  <a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/v/tenvoy.svg?sanitize=true" alt="Version"></a>
-  <a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/l/tenvoy.svg?sanitize=true" alt="License"></a>
-  <a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/dm/tenvoy.svg?sanitize=true" alt="Monthly Downloads"></a>
-  <a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/dt/tenvoy.svg?sanitize=true" alt="Total Downloads"></a>
+	<a href="https://github.com/TogaTech/tEnvoy/actions"><img src="https://img.shields.io/github/workflow/status/TogaTech/tEnvoy/Node.js%20CI" alt="Build Status"></a>
+	<a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/v/tenvoy.svg?sanitize=true" alt="Version"></a>
+	<a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/l/tenvoy.svg?sanitize=true" alt="License"></a>
+	<a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/dm/tenvoy.svg?sanitize=true" alt="Monthly Downloads"></a>
+	<a href="https://www.npmjs.com/package/tenvoy"><img src="https://img.shields.io/npm/dt/tenvoy.svg?sanitize=true" alt="Total Downloads"></a>
 </p>
 
 PGP, NaCl, and PBKDF2 in node.js and the browser (hashing, random, encryption, decryption, signatures, conversions), used by [TogaTech.org](https://togatech.org/)
 
+# Table of Contents
+- [Imports](#imports)
+	- [Browser Import](#browser-import)
+	- [Node.js NPM Import](#nodejs-npm-import)
+	- [Node.js File Import](#nodejs-file-import)
+- [Minify](#minify)
+- [Dependencies](#dependencies)
+- [Quickstart](#quickstart)
+- [Documentation](#documentation)
+	- [General](#general)
+	- [Core](#core)
+	- [Utilities](#utilities)
+	- [Random](#random)
+	- [Hashing](#hashing)
+	- [Key Factory](#key-factory)
+	- [PGP Keys](#pgp-keys)
+	- [NaCl Keys](#nacl-keys)
+	- [NaCl Signing Keys](#nacl-signing-keys)
+- [Cryptography Notice](#cryptography-notice)
+
 # Imports
 
 ## Browser Import
@@ -23,7 +43,7 @@ For the browser, only `./tenvoy.js` or `./tenvoy.min.js` is required and has all
 ```html
 <script type="text/javascript" src="./tenvoy.min.js"></script>
 <script>
-  const envoy = new tEnvoy();
+	const envoy = new tEnvoy();
 </script>
 ```
 
@@ -63,7 +83,7 @@ const { tEnvoy, tEnvoyPGPKey, tEnvoyNaClKey, tEnvoyNaClSigningKey } = require(".
 const envoy = new tEnvoy();
 ```
 
-## Minify
+# Minify
 If you would like to minify the code yourself instead of using the provided `tenvoy.min.js` (and optional `tenvoy.min.js.map`), you can use [UglifyJS 3](https://github.com/mishoo/UglifyJS) to minifiy the code yourself.
 
 To install UglifyJS 3 as a command line app through NPM, run `npm install uglify-js -g`.
@@ -74,6 +94,264 @@ uglifyjs ./tenvoy.js -o ./tenvoy.min.js -c -m --source-map "filename='./tenvoy.m
 uglifyjs ./node/tenvoy.js -o ./node/tenvoy.min.js -c -m --source-map "filename='./node/tenvoy.min.js.map',url='tenvoy.min.js.map'"
 ```
 
+# Dependencies
+
+# Quickstart
+
+# Documentation
+
+## General
+
+### constructor
+Creates a new instance of tEnvoy
+```javascript
+const envoy = new tEnvoy(openpgp, nacl, sha256); // tEnvoy {...}
+```
+For browsers only, a static `window` property contains an instance of tEnvoy by default. This instance is less secure than creating your own scoped instance (due to prototype pollution vulnerabilities) but can be helpful for debugging purposes in the browser console:
+```javascript
+const envoy = window.TogaTech.tEnvoy; // tEnvoy {...}
+```
+**Parameters:**
+- openpgp (optional, default: `openpgp`): Object (`openpgp`) - a valid instance of OpenPGP.js (https://github.com/openpgpjs/openpgpjs), `openpgp` is added by default in `tenvoy.js`, but this parameter can be used to provide a modified version of `openpgp` or a polyfill
+- nacl (optional, default: `nacl`): Object (`nacl`) - a valid instance of TweetNaCl.js (https://github.com/dchest/tweetnacl-js), `nacl` is added by default in `tenvoy.js`, but this parameter can be used to provide a modified version of `nacl` or a polyfill
+- sha256 (optional, default: `sha256`): Object (`sha256`) - a valid instance of fasth-sha256-js (https://github.com/dchest/fast-sha256-js), `sha256` is added by default in `tenvoy.js`, but this parameter can be used to provide a modified version of `sha256` or a polyfill
+
+**Return Type:** tEnvoy (`tEnvoy {...}`)
+
+### wordsList
+Gets or sets the [BIP39 English wordlist](https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt) as an array of 2048 words, used to generate random words or back up/restore NaCl-based keys
+```javascript
+let dictionary = envoy.dictionary;  // (2048) ['abandon', 'ability', 'able', 'about', ...]
+envoy.dictionary = ['abandon', 'ability', 'able', 'about', ...];
+```
+**Type:** Array (`(2048) ['abandon', 'ability', 'able', 'about', ...]`)
+
+**Warning: It is not recommended to modify envoy.dictionary.**
+
+### version
+Gets the version (read-only) of tEnvoy
+```javascript
+let version = envoy.version; // "v7.0.8"
+```
+**Type:** string (`"v7.0.8"`)
+
+## Core
+
+### core.openpgp
+Gets the instance of `openpgp` (read-only) for tEnvoy (can be set in the constructor)
+```javascript
+let openpgp = envoy.core.openpgp; // {...}
+```
+**Type:** Object (`{...}`)
+
+### core.nacl
+Gets the instance of `nacl` (read-only) for tEnvoy (can be set in the constructor)
+```javascript
+let nacl = envoy.core.nacl; // {...}
+```
+**Type:** Object (`{...}`)
+
+### core.sha256
+Gets the instance of `sha256` (read-only) for tEnvoy (can be set in the constructor)
+```javascript
+let sha256 = envoy.core.sha256; // {...}
+```
+**Type:** Object (`{...}`)
+
+## Utilities
+
+### util.utf8encode
+
+### util.utf8decode
+
+### util.stringToBytes
+
+### util.bytesToString
+
+### util.stringToHex
+
+### util.hexToString
+
+### util.bytesToHex
+
+### util.hexToBytes
+
+### util.arrayDeepCopy
+
+### util.compareConstant
+
+### util.mixedToUint8Array
+
+### util.uint8ArrayToMixed
+
+### util.pack
+
+### util.unpack
+
+### util.objectEquals
+
+### util.fixArmor
+
+## Random
+
+### random.bytes
+
+### random.number
+
+### random.string
+
+### random.words
+
+## Hashing
+
+### hash
+
+### hash.sha256
+
+### hash.sha1
+
+### hash.sha224
+
+### hash.sha384
+
+### hash.sha512
+
+### hash.md5
+
+### hash.ripemd160
+
+## Key Factory
+
+### keyFactory.pbkdf2
+
+### keyFactory.genSeedFromCredentials
+
+### keyFactory.genPGPKeys
+
+### keyFactory.genPGPSymmetricKey
+
+### keyFactory.genNaClKeys
+
+### keyFactory.genNaClSymmetricKey
+
+## PGP Keys
+
+### constructor
+
+### tEnvoyPGPKey.destroy
+
+### tEnvoyPGPKey.toString
+
+### tEnvoyPGPKey.getType
+
+### tEnvoyPGPKey.getPasswordProtected
+
+### tEnvoyPGPKey.setPasswordProtected
+
+### tEnvoyPGPKey.getId
+
+### tEnvoyPGPKey.getKey
+
+### tEnvoyPGPKey.getPrivate
+
+### tEnvoyPGPKey.setPrivate
+
+### tEnvoyPGPKey.getPrivateArmored
+
+### tEnvoyPGPKey.setPrivateArmored
+
+### tEnvoyPGPKey.getPublic
+
+### tEnvoyPGPKey.setPublic
+
+### tEnvoyPGPKey.getPublicArmored
+
+### tEnvoyPGPKey.setPublicArmored
+
+### tEnvoyPGPKey.encrypt
+
+### tEnvoyPGPKey.decrypt
+
+### tEnvoyPGPKey.sign
+
+### tEnvoyPGPKey.verify
+
+### tEnvoyPGPKey.toPublic
+
+## NaCl Keys
+
+### constructor
+
+### tEnvoyNaClKey.destroy
+
+### tEnvoyNaClKey.toString
+
+### tEnvoyNaClKey.getType
+
+### tEnvoyNaClKey.getPasswordProtected
+
+### tEnvoyNaClKey.setPasswordProtected
+
+### tEnvoyNaClKey.getPrivate
+
+### tEnvoyNaClKey.setPrivate
+
+### tEnvoyNaClKey.getPublic
+
+### tEnvoyNaClKey.setPublic
+
+### tEnvoyNaClKey.backup
+
+### tEnvoyNaClKey.fromBackup
+
+### tEnvoyNaClKey.encrypt
+
+### tEnvoyNaClKey.decrypt
+
+### tEnvoyNaClKey.encryptEphemeral
+
+### tEnvoyNaClKey.decryptEphemeral
+
+### tEnvoyNaClKey.genSigningKeys
+
+### tEnvoyNaClKey.genSharedKey
+
+### tEnvoyNaClKey.toPublic
+
+## NaCl Signing Keys
+
+### constructor
+
+### tEnvoyNaClSigningKey.destroy
+
+### tEnvoyNaClSigningKey.toString
+
+### tEnvoyNaClSigningKey.getType
+
+### tEnvoyNaClSigningKey.getPasswordProtected
+
+### tEnvoyNaClSigningKey.setPasswordProtected
+
+### tEnvoyNaClSigningKey.getPrivate
+
+### tEnvoyNaClSigningKey.setPrivate
+
+### tEnvoyNaClSigningKey.getPublic
+
+### tEnvoyNaClSigningKey.setPublic
+
+### tEnvoyNaClSigningKey.backup
+
+### tEnvoyNaClSigningKey.fromBackup
+
+### tEnvoyNaClSigningKey.sign
+
+### tEnvoyNaClSigningKey.verify
+
+### tEnvoyNaClSigningKey.verifyWithMessage
+
+### tEnvoyNaClSigningKey.toPublic
+
 # Cryptography Notice
 This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.