Zenroomjs provides a javascript wrapper of Zenroom, a secure and small virtual machine for crypto language processing.
🚧 Zenroom and Zenroomjs are part of the DECODE project about data-ownership and technological sovereignty. Our effort is that of improving people's awareness of how their data is processed by algorithms, as well facilitate the work of developers to create along privacy by design principles using algorithms that can be deployed in any situation without any change. |
yarn add zenroomTo start using the zenroom module just
const zenroom = require('zenroom').defaultor with ES6 syntax:
import zenroom from 'zenroom'the zenroomjs module is architectured as a Revealing Module Pattern this also means that once you set some options it will remain till the object lifetime, unless you reset or overwrite them.
Another used paradigm is method chaining this means that you can chain the different methods, let's see some hello worldish example:
import zenroom from 'zenroom'
// or without es6 syntax
// const zenroom = require('zenroom').default
const script = `print("hello world from zenroom in nodejs")`
zenroom.script(script).zenroom_exec()
// prints in the console.log "hello world from zenroom in nodejs"To initialize the options there are two ways, the one with the chaining that we saw before or a handy init() method to make them in one shot
// method chaining
zenroom.script('print("hello world")')
.verbosity(1)
.success(() => { console.log('everything goes smooth') })
.error(() => { console.error('something very bad happened') })
.zenroom_exec()
.reset() // cleans up the session// using the init() method
options = {
script: 'print("hello world")',
verbosity: 1,
success: () => { console.log('everything goes smooth') },
error: () => { console.error('something very bad happened') }
}
zenroom.init(options).zenroom_exec()All the available options and method are covered in the next API section
Set the zenroom script to run
The syntax of the zenroom scripts are extensively available at https://zenroom.dyne.org/api/tutorials/Syntax.html You may want also to look at some example in a live executable environment here https://zenroom.dyne.org/demo/
scriptstring the lua script to be set
Example usage of script()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = 'print("hello")'
zenroom.script(script).zenroom_exec().reset()Returns zenroom the zenroom module
Set the keys JSON for you zenroom execution
the keys will be available in script as the KEYS variable
keysobject the keys to be set as an object
Example usage of keys()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = `
keys = JSON.decode(KEYS)
print(keys)
`
const keys = {a: 1, b: 2}
zenroom.script(script).keys(keys).zenroom_exec().reset()Returns object the zenroom module
Set the data for your zenroom execution
The data will be available in script as the DATA variable
datastring
Example usage of data()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = `
data = JSON.decode(DATA)
print(data)
`
const data = {a: 1, b: 2}
zenroom.script(script).data(data).zenroom_exec()Returns object the zenroom module
Set the conf before your zenroom execution
all the available configuration are available here
confstring the string of configuration to be set
Example usage of conf()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = 'print("hello")'
const conf = 'debug=1,memwipe=0'
zenroom.script(script).conf(conf).zenroom_exec()Returns object the zenroom module
Set the print_err callback to customize the behaviour of the print_err calls made to stderr by default it prints to the console.error
Type: Function
Example usage of print_err()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const savedLines = []
const print_err_fn = (text) => { savedLines.push(text) }
const script = 'print("hello")'
zenroom.print_err(print_err_fn).script(script).zenroom_exec()Returns object the zenroom module
Set the print callback to customize the behaviour of the print calls made to stdout by default it prints to the console.log
Type: Function
Example usage of print()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const savedLines = []
const printFunction = (text) => { savedLines.push(text) }
const script = 'print("hello")'
zenroom.print(printFunction).script(script).zenroom_exec()Returns object the zenroom module
Set the success callback that is executed after a successful execution of zenroom
Type: Function
Example usage of success()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = 'print("hello")'
zenroom.script(script).success(()=>{
pleaseRunSomeOtherMethodAfter()
}).zenroom_exec()Returns object the zenroom module
Set the error callback that is executed after an unsuccessful execution of zenroom
Type: Function
Example usage of error()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = 'print("hello")';
zenroom.script(script).error(()=>{
pleaseRunSomeOtherMethodAfterError()
}).zenroom_exec()Returns object the zenroom module
Execute the zenroom vm (using the previously setted options)
It is usually the last method of the chain, but like the other methods returns the zenroom module itself, so can be used for other calls if you need to make more executions in a row
Example usage of zenroom_exec()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = 'print("hello")';
zenroom.script(script).zenroom_exec()Returns object the zenroom module
Execute zencode contracts (using the previously setted options)
It is usually the last method of the chain, but like the other methods returns the zenroom module itself, so can be used for other calls if you need to make more executions in a row
Example usage of zencode_exec()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const zencode = 'print("hello")';
zenroom.script(script).zencode_exec()Returns object the zenroom module
This method allows the configuration of your call by passing one configuration option object. You can use the chain methods after this anyway.
If some attribute is already set, those will be overwritten by the new options
The following options are available:
- script
- keys
- conf
- data
- success
- error
options
Example usage of init()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const encrypt_secret_to_many = {
script: `keyring = ECDH.new()
secret = str(DATA)
keys = JSON.decode(KEYS)
keyring:private( base64(keys.keyring.secret) )
res = {}
for name,pubkey in pairs(keys.recipients) do
pub = base64(pubkey)
enc = ECDH.encrypt(keyring,pub,secret,keyring:public())
res[name] = str( MSG.pack( map(enc,base64) ) ):base64()
end
print(JSON.encode(res))`,
keys: {
keyring : {
public : "BHMjcDM/aljpi8pNxFQ436R6F3J+kaB/Xk1kAVFPmkoLVyeFltDZPgiIYRquh+m2IfvPioBfet7YCd5vVXYoRTk=",
secret : "ChW5qi5y//ISDIHKx5Fvxl+XY8IyDGVBHUfELp3PqJQ="
},
recipients : {
paulus : "BBUw6Nr3A30cN65maERvAk1cEv2Ji6Vs80kSlpodOC0SCtM8ucaS7e+s158uVMSr3BsvIXVspBeafiL8Qb3kcgc=",
mayo : "BHqBoQ2WJ3/FGVNTXzdIc+K/HzNx05bWzEhn8m58FvSsaqWVdH52jI6fQWdkdjnbqVKCJGmbjA/OCJ+IKHbiySI=",
mark : "BFgkjrRMvN+wkJ6qA4UvMaNlYBvl37C9cNYGkqOE4w43AUzkEzcyIIdE6BrgOEUEVefhOOnO6SCBQMgXHXJUUPY=",
francesca : "BCo102mVybieKMyhex8tnVtFM5+Wo1oP02k8JVwKF9OLIjw7w0LmofItbuAcfWl9rcoe++XLI3sySZnqljIfeyU=",
jim : "BEs1jeqL0nVwFi7OmG4YdtlWuKADyOvZR4XHpLAEswg8ONPXQHvwJ8+PkHkphoORfSjk2045bMdYkwboU4FdG2Y=",
jaromil : "BBZYJtHvFg0vGCxPROAWrThcGZ+vFZJj86k+uncjvbm4DysIg7cWS3J6GrcJKCY55Uf40m2KfBwfaT+T7TTO1e8="
}
},
data: 'This is a secret message.'
}
zenroom.init(encrypt_secret_to_many).zenroom_exec()Returns object the zenroom module
Reset the setted options already provided and cleans up the zenroom module
It is usually the last method of the chain, but like the other methods returns the zenroom module itself, so can be used for other calls if you need to make more executions in a row
Example usage of reset()
// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')
const script = 'print("hello")';
zenroom.script(script)
.zenroom_exec() // This runs the script
.reset()
.zenroom_exec() // This does not run the script anymoreReturns object the zenroom module
Copyright (C) 2018 by Dyne.org foundation, Amsterdam
Designed, written and maintained by Puria Nafisi Azizi.
This project is receiving funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement nr. 732546 (DECODE).
Please first take a look at the Dyne.org - Contributor License Agreement then
- FORK IT
- Create your feature branch
git checkout -b feature/branch - Commit your changes
git commit -am 'Add some fooBar' - Push to the branch
git push origin feature/branch - Create a new Pull Request
- Thank you
Zenroomjs - a javascript wrapper of zenroom
Copyright (c) 2019 Dyne.org foundation, Amsterdam
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.