vault-tree 0.3.4 → 0.6.0

data/features/contracts_and_vaults.md

@@ -4,9 +4,7 @@ Now that we've explored the ideas of a **Contract**, **Contract Enforcement**, a
 
 #### Vaults
 
-Vault Tree Contracts are made by assembling simple structures called **Vaults**.
-
-A vault is like a digital lock box that stores a single unambiguous piece of information. This piece of information is needed to continue the execution of a contract beyond a certain event.
+Vault Tree Contracts are made by assembling simple structures called **Vaults**. A vault is like a digital lock box that stores a single unambiguous piece of information.
 
 The light bulb should turn on when you realize that vaults can hold not only valuable external information, but the **keys to other vaults**.
 
@@ -21,6 +19,10 @@ benefit of being a **Distributed Cryptographic Contract**. This means:
 * Each Vault encrypts a piece of secret information. This can be external
 information such as a _URL_ or a _Bitcoin Wallet Address_. More often, a vault will contain the unlocking key to another vault in the contract.
 * The way in which the contract author **chooses to structure** the releationship between vaults, will determine how the contract is **Enforced**.
+* It is the responsibility of the contract author to arrange vaults so that there are no contract [moral hazards] or [perverse incentives].
+
+[moral hazards]: http://en.wikipedia.org/wiki/Moral_hazard
+[perverse incentives]: http://en.wikipedia.org/wiki/Perverse_incentive
 
 #### Complete Contracts
 
@@ -50,34 +52,29 @@ arranged to enforce the terms of the contract.
 Let's take a look at an example vault:
 
 ```javascript
-"bob_random_vault_key": {
+"bob_random_key": {
   "fill_with": "RANDOM_NUMBER",
-  "lock_with": "KEY['bob_vault_key']",
-  "unlock_with": "KEY['alice_vault_key']",
-  "contents": "rSGrWGL4mEYtpuIaWO/iVGXAA5UUyLeeImSV3SBXzb+C7DW3"
+  "lock_with": "KEY['bob_first_vault_key']",
+  "unlock_with": "KEY['alice_third_vault_key']",
+  "contents": "dc92c330e5f911e3ac100800200c9a6648ab522cf91739ade ... "
 }
 ```
 
-It's important to keep in mind that, **every** vault follows this format. This convention for representing a vault should be sufficient to build any type of simplistic or sophisticated contract.
+It's important to keep in mind that, **every** vault follows this format. This
+convention for representing a vault should be sufficient to build any type of
+simple or sophisticated contract.
 
 #### Vault Id
 
-The **Vault Id** can be thought of as both the name and the **Unique** identifier of the vault.
+The **Vault Id** can be thought of as both the name and the **unique** identifier of the vault.
 
 In this case we have:
 
 ```
-"bob_random_vault_key"
+"bob_random_key"
 ```
 
-Try to give meaningful names that give insight into the locked contents held within the vault. Also, by convention vault names should begin with the name of the vault owner.
-
-A vault owner is the contract party that is responsibily for filling and locking the vault. In this simple case we have **bob**, but in an employment contract for example, we may have vault owners named **employer** and **employee**.
-
-It is the responsibility of the contract author to assign vault owners in such a way that there are no contract [moral hazards] or [perverse incentives].
-
-[moral hazards]: http://en.wikipedia.org/wiki/Moral_hazard
-[perverse incentives]: http://en.wikipedia.org/wiki/Perverse_incentive
+Try to give meaningful names that give insight into the locked contents held within the vault.
 
 #### Fill With
 
@@ -103,25 +100,23 @@ The **unlock_with** field naturally identifies the source of the vault's **Unloc
 
 It may not be obvious, but the reference to the Unlocking key does not necessarily need to be the same as the reference to the **Locking Key**. Here are some examples of where this could be the case: 
 
-* The same key is used to lock and unlock the vault, but copies of this key are
-* held in two separate vaults. Take a look at the **Block Chain Key Transfer**
-* contract to see a good example of this.
+* The same key is used to lock and unlock the vault, but copies of this key are held in two separate vaults. Take a look at the **Block Chain Key Transfer** contract to see a good example of this.
 * Vault Tree supports the notion of an **Asymmetric Vault** through the _DSL Keyword_
 
 ```
 DH_KEY
 ```
 
-An Asymmetric Vault is locked and unlocked with the help of a [Public-Private](http://en.wikipedia.org/wiki/Public-key_cryptography) keypair. Vault Tree's underlying cryptographic library makes this possible by implementing a cutting edge variant of the [ECDH] key exchange protocol.  
+An Asymmetric Vault is locked and unlocked with the help of a [Public-Private](http://en.wikipedia.org/wiki/Public-key_cryptography) keypair. Vault Tree's underlying cryptographic library makes this possible by implementing a cutting edge variant of the [ECDH] key exchange protocol.
 
 [ECDH]: http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman
 
 #### Contents
 
-As you would expect, this field references the encrypted contents of the vault. In the example above you can see the _Base 64_ encoded ciphertext:
+As you would expect, this field references the encrypted contents of the vault. In the example above you can see the _Hex_ encoded ciphertext:
 
 ```
-"contents": "rSGrWGL4mEYtpuIaWO/iVGXAA5UUyLeeImSV3SBXzb+C7DW3"
+"contents": "dc92c330e5f911e3ac100800200c9a6648ab522cf91739ade ... "
 ```
 Here are some items to keep in mind:
 

data/features/decision_tree.md

@@ -7,7 +7,7 @@ Contracts can be modeled as a [Decision Tree]. Intuitively this means that:
 * **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.
+* **Well Written** contracts correspond to well structured graphs.
 
 [Directed Graph]: http://en.wikipedia.org/wiki/Directed_graph
 [Tree]: http://en.wikipedia.org/wiki/Tree_%28graph_theory%29 

data/features/exceptions.feature

@@ -1,28 +1,23 @@
 Feature: Vault Tree Exceptions
 
-Scenario: Empty Vault
-  Given the broken contract
-  When I attempt to open an empty vault
-  Then an EmptyVault exception is raised
+  The library trys to anticipate common usage errors. A
+  custom error with a helpful message should be raised if there
+  is a problem with you contract.
 
-Scenario: Attempted Fill with Master Password 
-  Given the broken contract
-  When I attempt fill a vault with my Master Password  
-  Then a FillAttemptMasterPassword exception is raised
+  If you do run across an unexpected ruby runtime error, please
+  file a Github issue. I want to make the experience of executing
+  and debugging your own contracts as painless as possible.
 
-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
+  Thanks!
 
-Scenario: Missing External Data On Lock
+Scenario: Unsupported Keyword
   Given this broken contract:
     """javascript
       {
         "header": {},
         "vaults": {
-          "missing_external_data_vault":{
-            "fill_with": "EXTERNAL_DATA",
+          "unsupported_keyword":{
+            "fill_with": "UNSUPPORTED_KEYWORD",
             "lock_with": "UNLOCKED",
             "unlock_with": "UNLOCKED",
             "contents": ""
@@ -30,63 +25,79 @@ Scenario: Missing External Data On Lock
         }
       }
     """
-  When I attempt lock a vault with External Data that does not exists
-  Then a MissingExternalData exception is raised
+  When I attempt fill a vault with an unsupported Keyword
+  Then an UnsupportedKeyword exception is raised
 
-Scenario: Missing External Data On Unlock
+Scenario: Vault Does Not Exists on Retrieval
   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.",
+
+          "empty_vault":{
             "fill_with": "RANDOM_NUMBER",
-            "lock_with": "RANDOM_NUMBER",
-            "unlock_with": "EXTERNAL_DATA",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
             "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
-  When I attempt fill a vault with an unsupported Keyword
-  Then an UnsupportedKeyword exception is raised
-
-Scenario: Vault Does Not Exists on Retrieval
-  Given the broken contract
   When I attempt to open a vault that does not exists
   Then a VaultDoesNotExist exception is raised
 
 Scenario: Vault Does Not Exists on Closing
-  Given the broken contract
+  Given this broken contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+
+          "empty_vault":{
+            "fill_with": "RANDOM_NUMBER",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          }
+        }
+      }
+    """
   When I attempt to close a vault that does not exists
   Then a VaultDoesNotExist exception is raised
 
-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":{
+          "some_random_vault":{
             "fill_with": "RANDOM_NUMBER",
-            "lock_with": "EXTERNAL_DATA",
-            "unlock_with": "EXTERNAL_DATA",
+            "lock_with": "EXTERNAL_INPUT['right_secret']",
+            "unlock_with": "EXTERNAL_INPUT['wrong_secret']",
             "contents": ""
           }
         }
       }
     """
-  When I lock a vault with External Data and attempt to unlock with the wrong External Data
+  When I lock a vault with External Input and attempt to unlock with the wrong External Input
   Then a FailedUnlockAttempt exception is raised
+
+Scenario: Missing External Input On Lock
+  Given this broken contract:
+    """javascript
+      {
+        "header": {},
+        "vaults": {
+          "missing_external_input_vault":{
+            "fill_with": "EXTERNAL_INPUT['empty_value']",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          }
+        }
+      }
+    """
+  When I attempt lock a vault with External Input that does not exists
+  Then an InvalidExternalInput exception is raised

data/features/install_and_usage.md

@@ -1,57 +1,62 @@
-Make sure you checkout the README in the [Github Repo] for the full install documentation.
+### Install
 
-[Github Repo]: https://github.com/VaultTree/vault-tree
+As a prerequisite, get [libsodium] version (>= 0.4.3) on you machine. This is the underlying cryptographic library that Vault Tree depends on.
 
-### Install With Vagrant
+[libsodium]: https://github.com/jedisct1/libsodium
 
-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!
+* If you are on _OSX_ there is a [brew] package available. So just:
 
-* Follow the [Vagrant] download and install steps
-* Clone the Vault Tree Repo and go into it:
+  ```
+  brew install libsodium
+  ```
 
-[Vagrant]: http://www.vagrantup.com/
+[brew]: http://brew.sh/
 
-```shell
-git clone git@github.com:VaultTree/vault-tree.git
-cd ~/path/to/vault-tree/
+* If you're on a Debian based system, there is no _apt-get_ package that I know of, but there
+  are some helpful install scripts on the web.
+
+Now that you have libsodium, if you're a Ruby developer you know the drill from here:
+
+```ruby
+gem install vault-tree
 ```
 
-Now you just need to Vagrant Up!
+and then
 
-```shell
-vagrant up
+```ruby
+require 'vault-tree'
 ```
+somewhere before you use it.
+
+### Usage
 
-This will download and boot a pre-packaged Linux virtual machine with Vault-Tree and all dependencies already installed.
+Executing contracts in your Ruby application is is simple.
 
-Once your VM is downloaded and built. You can go inside with:
+Instantiate a new contract object with its corresponding JSON:
 
-```shell
-vagrant ssh
+```ruby
+  @contract = VaultTree::Contract.new(contract_json)
 ```
 
-As a developer working on Vault Tree you can now go to the VM's directory:
+From here you have two methods available:
 
+```ruby
+  @contract.close_vault('vault_id', external_input = {})
 ```
-/vagrant
-```
-and run
 
+```ruby
+  @contract.open_vault('vault_id', external_input = {})
 ```
-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.
+### Testing
 
-[vault-tree]: https://github.com/VaultTree/vault-tree
-[main repo]: https://github.com/VaultTree/vault-tree
-[Ruby Gems]: http://rubygems.org
+A great way to get going is to simply run the tests:
 
-### Install With Bundler
+* clone the repo
+* bundle your dependencies
+* run `rake`
 
-If you are comfortable with Ruby and Bundler checkout the README in the [main repo] to get started with a direct install.
+You should see a full suite of green tests that will give you plenty of living
+examples of to use Vault Tree in your own application.
 
-[main repo]: https://github.com/VaultTree/vault-tree
+[Documentation]: https://www.relishapp.com/vault-tree/vault-tree/docs

data/features/keywords/assembled_shamir_key.feature

@@ -7,51 +7,51 @@ Scenario: Lock with Generated Key. Unlock with Assembled Shamir Key
         "header": {},
         "vaults": {
           "s_1":{
-            "fill_with": "EXTERNAL_DATA",
+            "fill_with": "SHAMIR_SHARE['share_collection','1']",
             "lock_with": "UNLOCKED",
             "unlock_with": "UNLOCKED",
             "contents": ""
           },
-
           "s_2":{
-            "fill_with": "EXTERNAL_DATA",
+            "fill_with": "SHAMIR_SHARE['share_collection','2']",
             "lock_with": "UNLOCKED",
             "unlock_with": "UNLOCKED",
             "contents": ""
           },
-
           "s_3":{
-            "fill_with": "EXTERNAL_DATA",
+            "fill_with": "SHAMIR_SHARE['share_collection','3']",
             "lock_with": "UNLOCKED",
             "unlock_with": "UNLOCKED",
             "contents": ""
           },
-
           "s_4":{
-            "fill_with": "EXTERNAL_DATA",
+            "fill_with": "SHAMIR_SHARE['share_collection','4']",
             "lock_with": "UNLOCKED",
             "unlock_with": "UNLOCKED",
             "contents": ""
           },
-
           "s_5":{
-            "fill_with": "EXTERNAL_DATA",
+            "fill_with": "SHAMIR_SHARE['share_collection','5']",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
+            "contents": ""
+          },
+          "share_collection":{
+            "fill_with": "SHAMIR_KEY_SHARES['5','3']",
             "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']",
+            "fill_with": "EXTERNAL_INPUT['msg']",
+            "lock_with": "ASSEMBLED_SHAMIR_KEY['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
+  When I lock away the shamir key share collection
+  And I close the key shares in their respective vaults
+  Then I can lock away a message with the key assembled from the shares
+  And if all the shares are available I can unlock the message

data/features/keywords/dh_key.feature

@@ -18,15 +18,15 @@ Scenario: Asymmetric Vault
         "header": {},
         "vaults": {
           "asymmetric_message":{
-            "fill_with": "EXTERNAL_DATA",
+            "fill_with": "EXTERNAL_INPUT['asymmetric_message']",
             "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",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
             "contents": ""
           },
           "my_public_key":{
@@ -37,8 +37,8 @@ Scenario: Asymmetric Vault
           },
           "another_decryption_key":{
             "fill_with": "DECRYPTION_KEY",
-            "lock_with": "MASTER_PASSPHRASE",
-            "unlock_with": "MASTER_PASSPHRASE",
+            "lock_with": "UNLOCKED",
+            "unlock_with": "UNLOCKED",
             "contents": ""
           },
           "another_public_key":{

data/features/keywords/external_input.feature

@@ -0,0 +1,35 @@
+Feature: External Inputs
+
+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 inputs will be explicitly passed in.
+
+Use the EXTERNAL_INPUT Keyword when you want to fill a vault with a string from
+the outside environment.
+
+Although you can lock and unlock vaults directly with an EXTERNAL_INPUT string
+if it happens to be properly formated, it is recommended that you do not do this.
+
+Instead, lock and unlock vaults with external strings using the EXTERNAL_KEY phrase.
+EXTERNAL_KEY ensures your password is run through a secure hash before it is used to
+lock contents. Hashing guarentees a properly padded vault key and keeps the locked vault
+more secure if you have a weak password.
+
+  Scenario: Close And Open Using with a Key
+    Given the blank contract:
+      """javascript
+        {
+          "header": {},
+          "vaults": {
+            "message":{
+              "description": "Simple Congratulations Message",
+              "fill_with": "EXTERNAL_INPUT['msg']",
+              "lock_with": "EXTERNAL_INPUT['secret']",
+              "unlock_with": "EXTERNAL_INPUT['secret']",
+              "contents": ""
+            }
+          }
+        }
+      """
+    When I lock the external input in a vault using a symmetric vault key
+    Then I can recover the input message using the same key