vault-tree 0.1.0 → 0.3.3

data/features/contributing_to_vault_tree.md

@@ -0,0 +1,42 @@
+### Submitting a New Contract
+
+The example contracts in this documentation are a small collection that have been assembled for illustrative purposes. We can learn from these simplified examples, and use them as the foundation for more complex _real world_ contracts.
+
+I encourage **anyone** interested, to submit new and innovative contracts. Here are some items to keep in mind when you are ready to contribute:
+  * Vault Tree was designed so that smart people of all different backgrounds could design and execute contracts. Don't feel that you need to be a programmer to get started.
+  * Try to familiarize yourself with Github best practices. Do you best understand Pull Requests before you attempt to submit.
+
+### Design Opinions
+
+Vault Tree was written to give contract authors a large amount of flexibilty.  There are however some design constraints that were put in place to get the community off to a good start.
+
+I'll update these in the coming months as we get some more experience writing simple contracts.
+  * The Vault Tree interpreter is stateless and always takes a contract as an input
+  * All external data required for contract execution must be provided to the interpreter by the run time that is invoking the API. For example, there are no plans for the interpreter to make any network requests or do file IO.
+
+##### Notes for Developers
+
+* Let's practice strict [semantic versioning] in managing our contracts.
+* Edit contracts with the help of an application like [js beatifier].
+* Ensure proper JSON format with a tool like this [json parser].
+* Changes to core contracts should produce clean Git diffs.
+
+[lab]: https://github.com/VaultTree/contracts/tree/master/lab
+[core]: https://github.com/VaultTree/contracts/tree/master/core
+[Contracts Repository]: https://github.com/VaultTree/contracts 
+[JSON]: http://www.json.org 
+[Vault Tree Homepage]: http://www.vault-tree.org
+[Vault Tree Project]: http://www.vault-tree.org
+[semantic versioning]: http://semver.org
+[js beatifier]: http://jsbeautifier.org 
+[json parser]: http://json.parser.online.fr
+[json]: http://json.org
+
+##### Website Documentation
+
+A few comments on documentation:
+
+* The website documentation is generated from the `*.features/` and `*.md` files in this project.
+* We will standardize on Github flavored markdown
+* As you build contracts and solve problems please consider contributing back to the documentation. It's time consuming but extremely important for the life of the project.
+* Respect the established file naming conventions. Docs are generated with a build tool that makes assumptions.

data/features/decision_tree.md

@@ -0,0 +1,16 @@
+### Contracts as Decision Trees
+
+Contracts can be modeled as a [Decision Tree]. Intuitively this means that:
+
+* The set of contract events and final outcomes for all parties involved can be represented as a [Directed Graph].
+* Often, the graph will take the form of a [Tree].
+* **Events** are represented as nodes in the graph, **Outcomes** are events that correspond to [Leaf Nodes].
+* Once a contract has been **Negotiated**, contract execution proceeds down the graph beginning at the [Root Node].
+* Edges in the graph correspond to real world conditions that must be met before making a valid trasition between two events.
+* **Well Written** contracts, in the eyes of all parties, correspond to well structured graphs.
+
+[Directed Graph]: http://en.wikipedia.org/wiki/Directed_graph
+[Tree]: http://en.wikipedia.org/wiki/Tree_%28graph_theory%29 
+[Decision Tree]: http://en.wikipedia.org/wiki/Decision_tree
+[Leaf Nodes]: http://en.wikipedia.org/wiki/Tree_%28data_structure%29#Terminology
+[Root Node]: http://en.wikipedia.org/wiki/Tree_%28data_structure%29#Terminology

data/features/enforcement_problem.md

@@ -0,0 +1,20 @@
+Contracts become pointless if their terms cannot be effectly **enforced**. This enforcement problem is handled differently depenending on the nature of the contract and the parties involved.
+
+One of the most primative, widespread, and **decentalized** enforcement mechanisms in the world is the **Network of Trust**. Breach of contract, even if no legal action is taken, undermines the reputation of of the offending party. This can translate into substantial costs and acts as an incentive toward honorable conduct.
+
+In many cases however, a network of trust is an insufficient mechanism. When parties expect a more explict enforcement of their contract, they often turn to **centralized** solutions. Examples could include:
+  * Legal action within a justice system
+  * Private third party arbitration
+
+This type of enforcement works well when the central enforcing authority is:
+  * Agreed to by all contract participants
+  * Competent and Efficient
+  * Trustworthy
+
+Centralized enforcement is less effective or impossible when:
+  * Participants are distributed globally
+  * Business is conducted with a cutting edge internet finacial system that is ahead of established legal precedent
+  * Good people are are trying to conduct honorable business under extremely corrupt or incompetent legal systems
+
+
+

data/features/exceptions.feature

@@ -10,15 +10,48 @@ Scenario: Attempted Fill with Master Password
   When I attempt fill a vault with my Master Password  
   Then a FillAttemptMasterPassword exception is raised
 
-Scenario: Missing External Data
+Scenario: Missing External Data On Vault Fill
   Given the broken contract
   When I attempt fill a vault with External Data that does not exists
   Then a MissingExternalData exception is raised
 
-Scenario: Missing Passphrase
-  Given a valid blank contract
-  When I attempt fill a vault without providing a master passphrase 
-  Then a MissingPassphrase exception is raised
+Scenario: Missing External Data On Lock
+  Given this broken contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+          "missing_external_data_vault":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          }
+        }
+      }
+    """
+  When I attempt lock a vault with External Data that does not exists
+  Then a MissingExternalData exception is raised
+
+Scenario: Missing External Data On Unlock
+  Given this broken contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+          "missing_external_data_vault":{
+            "description": "The external data is not provided in the initialzer. See the step definitions in this case.",
+            "fill_with": "RANDOM_NUMBER",
+            "lock_with": "RANDOM_NUMBER",
+            "unlock_with": "EXTERNAL_DATA",
+            "contents": ""
+          }
+        }
+      }
+    """
+  When I lock the data away
+  And I attempt to unlock a vault with External Data that does not exists
+  Then a MissingExternalData exception is raised
 
 Scenario: Unsupported Keyword
   Given the broken contract
@@ -39,3 +72,21 @@ Scenario: Missing Partner Decryption Key
   Given the broken contract
   When I attempt to fill with an encryption key without first establishing the decryption key
   Then a MissingPartnerDecryptionKey exception is raised
+
+Scenario: Failed Symmetric Unlock Attempt
+  Given this broken contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+          "missing_external_data_vault":{
+            "fill_with": "RANDOM_NUMBER",
+            "lock_with": "EXTERNAL_DATA",
+            "unlock_with": "EXTERNAL_DATA",
+            "contents": ""
+          }
+        }
+      }
+    """
+  When I lock a vault with External Data and attempt to unlock with the wrong External Data
+  Then a FailedUnlockAttempt exception is raised

data/features/install_and_usage.md

@@ -0,0 +1,57 @@
+Make sure you checkout the README in the [Github Repo] for the full install documentation.
+
+[Github Repo]: https://github.com/VaultTree/vault-tree
+
+### Install With Vagrant
+
+I think it should be easy for you to get a Vault Tree development environment up and running. If you don't know about Vagrant, you should, it's awesome!
+
+* Follow the [Vagrant] download and install steps
+* Clone the Vault Tree Repo and go into it:
+
+[Vagrant]: http://www.vagrantup.com/
+
+```shell
+git clone git@github.com:VaultTree/vault-tree.git
+cd ~/path/to/vault-tree/
+```
+
+Now you just need to Vagrant Up!
+
+```shell
+vagrant up
+```
+
+This will download and boot a pre-packaged Linux virtual machine with Vault-Tree and all dependencies already installed.
+
+Once your VM is downloaded and built. You can go inside with:
+
+```shell
+vagrant ssh
+```
+
+As a developer working on Vault Tree you can now go to the VM's directory:
+
+```
+/vagrant
+```
+and run
+
+```
+bundle
+rake
+```
+
+This will pull down the latest version of the code from [Ruby Gems] and then run all the core contracts and put you in a good spot to start exploring the library.
+
+If you're not already familiar, take a few minutes to learn about how Vagrant will [sync your files] to and from the guest machine.
+
+[vault-tree]: https://github.com/VaultTree/vault-tree
+[main repo]: https://github.com/VaultTree/vault-tree
+[Ruby Gems]: http://rubygems.org
+
+### Install With Bundler
+
+If you are comfortable with Ruby and Bundler checkout the README in the [main repo] to get started with a direct install.
+
+[main repo]: https://github.com/VaultTree/vault-tree

data/features/keywords/assembled_shamir_key.feature

@@ -0,0 +1,57 @@
+Feature: Assembled Shamir Key
+
+Scenario: Lock with Generated Key. Unlock with Assembled Shamir Key
+  Given the blank contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+          "s_1":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_2":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_3":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_4":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_5":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "message":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "GENERATED_SHAMIR_KEY['5','3','s_1','s_2','s_3','s_4','s_5']",
+            "unlock_with": "ASSEMBLED_SHAMIR_KEY['s_1','s_2','s_3','s_4','s_5']",
+            "contents": ""
+          }
+        }
+      }
+    """
+  And I create a new message
+  When I attempt to lock the message with a generated shamir key
+  Then key shares are created and locked away in their cooresponding vaults
+  When I attempt to unlock the message with the assembled shamir key
+  Then I successfully gather the locked shares and unlock the message

data/features/keywords/contents.feature

@@ -0,0 +1,24 @@
+Feature: Contents
+
+The `CONTENTS` keyword is used to fetch the contents of another vault:
+
+```javascript
+"fill_with": "CONTENTS['some_string']"
+```
+
+It takes one argument, the name of the vault holding the desired contents.
+
+The contents keyword should only be used in the **fill_with** field. If you want to use it in either
+
+the **lock_with** or **unlock_with** fields, you should consider the alias `KEY` instead.
+
+Here is an example of a vault that makes use of the `CONTENTS` keyword.
+
+```javascript
+"locked_message":{
+  "fill_with": "CONTENTS['message_locked_with_random_key']",
+  "lock_with": "KEY['unlocked_random_key']",
+  "unlock_with": "KEY['unlocked_random_key']",
+  "contents": ""
+}
+```

data/features/keywords/decryption_key.feature

@@ -0,0 +1,10 @@
+Feature: Decryption Key
+  
+Decryption keys are asymmetric private keys.
+
+```javascript
+"fill_with": "DECRYPTION_KEY",
+```
+
+When establishing a public private key pair, you need to generate the decryption
+key first and reference its vault when building the associated public key.

data/features/keywords/dh_key.feature

@@ -0,0 +1,56 @@
+Feature: DH Key
+
+```javascript
+DH_KEY['public_key_vault_id','decryption_key_vault_id']
+```
+This keyword enables the creation of **Asymmetric Vaults**.
+
+DH Keys are very powerful and Vault Tree is written to encourage contract authors to make use of asymmetric encryption.
+
+The underlying cryptographic library provides a set of expertly crafted opinionated conventions for using public keys. One such convention is [Mutual Authentication](http://en.wikipedia.org/wiki/Mutual_authentication) accomplished with the Elliptic Curve Diffie-Hellman key exchange protocol.
+
+Feel free to study the example contracts for some good ideas on how to use this powerful keyword.
+
+Scenario: Asymmetric Vault
+  Given the blank contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+          "asymmetric_message":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "DH_KEY['another_public_key','my_decryption_key']",
+            "unlock_with": "DH_KEY['my_public_key','another_decryption_key']",
+            "contents": ""
+          },
+          "my_decryption_key":{
+            "fill_with": "DECRYPTION_KEY",
+            "lock_with": "MASTER_PASSPHRASE",
+            "unlock_with": "MASTER_PASSPHRASE",
+            "contents": ""
+          },
+          "my_public_key":{
+            "fill_with": "PUBLIC_ENCRYPTION_KEY['my_decryption_key']",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+          "another_decryption_key":{
+            "fill_with": "DECRYPTION_KEY",
+            "lock_with": "MASTER_PASSPHRASE",
+            "unlock_with": "MASTER_PASSPHRASE",
+            "contents": ""
+          },
+          "another_public_key":{
+            "fill_with": "PUBLIC_ENCRYPTION_KEY['another_decryption_key']",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          }
+        }
+      }
+    """
+  And I have access to the another user's unlocked public key
+  And I lock a simple message with a DH Key
+  When I transfer the contract to the other user
+  Then they can create a DH Key and unlock the message

data/features/keywords/external_data.feature

@@ -0,0 +1,11 @@
+Feature: External Data
+
+The Vault Tree interpreter does not interact directly with outside networks. Its
+repsonsibility is limited to opening and closing vaults under the assumption
+that all necessary external data will be explicitly passed in.
+
+In short, you can expect the interpreter to stick to the following rules:
+
+* External Data is relevent only when **closing** a vault.
+* When a vault is being opened, the interpreter expects that all the necessary data has already been locked somewhere in the contract.
+* External Data must be a string

data/features/keywords/generated_shamir_key.feature

@@ -0,0 +1,55 @@
+Feature: Generated Shamir Key
+
+Scenario: Lock Away Key Shares With Generated Shamir Key
+  Given the blank contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+          "s_1":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_2":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_3":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_4":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "s_5":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+
+          "message":{
+            "fill_with": "EXTERNAL_DATA",
+            "lock_with": "GENERATED_SHAMIR_KEY['5','3','s_1','s_2','s_3','s_4','s_5']",
+            "unlock_with": "ASSEMBLED_SHAMIR_KEY['s_1','s_2','s_3','s_4','s_5']",
+            "contents": ""
+          }
+        }
+      }
+    """
+  And I create a new message
+  When I attempt to lock the message with a generated shamir key
+  Then key shares are created and locked away in their cooresponding vaults

data/features/keywords/key.feature

@@ -0,0 +1,38 @@
+Feature: Key
+
+  This keyword is an alias of the the `CONTENTS` keyword:
+
+  ```javascript
+  KEY['vault_id']
+  ```
+
+  Note that:
+    * It should be used specifically when the contents are a Symmetric vault key.
+    * It takes one argument, the name of the vault holding the desired string.
+    * The `KEY` keyword can be used in the **fill_with**, **lock_with** and **unlock_with** fields.
+
+  Scenario: Close And Open Using with a Key
+    Given the blank contract:
+      """javascript
+        {
+          "header": {},
+          "vaults": {
+            "random_vault_key":{
+              "description":"Random Number",
+              "fill_with": "RANDOM_NUMBER",
+              "lock_with": "MASTER_PASSPHRASE",
+              "unlock_with": "MASTER_PASSPHRASE",
+              "contents": ""
+              },
+            "message":{
+              "description": "Simple Congratulations Message",
+              "fill_with": "EXTERNAL_DATA",
+              "lock_with": "KEY['random_vault_key']",
+              "unlock_with": "KEY['random_vault_key']",
+              "contents": ""
+            }
+          }
+        }
+      """
+    When I lock a message in a vault using a symmetric vault key
+    Then I can recover the message using the same key