@maidsafe/safe-node-app

0.3.0

External API

The externally exposed API

initializeApp

src/index.js

The main entry point to create a new SAFEApp

initializeApp(appInfo: AppInfo, networkStateCallBack: Function, options: InitOptions?): Promise<SAFEApp>
Parameters
appInfo (AppInfo)
networkStateCallBack (Function = null) callback function to receive network state updates
options (InitOptions?) initialisation options
Returns
Promise<SAFEApp>: promise to a SAFEApp instance
Example
// Usage Example
const safe = require('safe');

// starting initialisation
let prms = safe.initializeApp({
                     id: "net.maidsafe.example",
                     name: 'Example App',
                     vendor: 'MaidSafe Ltd.'
                    });
// we want read-append access to `_pictures` and
// read access to `_videos`:
const containers = { '_videos': ['Read'], '_pictures' : ['Read', 'Insert']}
prms.then(app => app.auth.genAuthUri(containers
          ).then(uri => app.auth.openUri(uri)
       // now we either quit the programm
       // or wait for a result url
       ))

fromAuthURI

src/index.js

If you have received a response URI (which you are allowed to store securely), you can directly get an authenticated or non-authenticated connection by using this helper function. Just provide said URI as the second value.

fromAuthURI(appInfo: AppInfo, authUri: String, networkStateCallBack: Function, options: InitOptions?): Promise<SAFEApp>
Parameters
appInfo (AppInfo) the app info
authUri (String) the URI coming back from the Authenticator
networkStateCallBack (Function = null) optional callback function to receive network state updates
options (InitOptions?) initialisation options
Returns
Promise<SAFEApp>: promise to a SAFEApp instance
AppInfo

Type: Object

Parameters
id (String) unique identifier for the app (e.g. 'net.maidsafe.examples.mail-app')
name (String) human readable name of the app (e.g. "Mail App")
vendor (String) human readable name of the vendor (e.g. "MaidSafe Ltd.")
scope (String?) an optional scope of this instance
customExecPath (String?) an optional customised execution path to use when registering the URI with the system.

InitOptions

src/index.js
InitOptions

Type: Object

Parameters
registerScheme (Boolean?) to register auth scheme with the OS. Defaults to true
log (Boolean?) to enable or disable back end logging. Defaults to true
libPath (String?) path to the folder where the native libs can be found. Defaults to current folder path.

App Interface

the App and the API it exposes

SAFEApp

src/app.js

Holds one sessions with the network and is the primary interface to interact with the network. As such it also provides all API-Providers connected through this session.

new SAFEApp(appInfo: any, networkStateCallBack: any, options: any)

Extends EventEmitter

Parameters
appInfo (any)
networkStateCallBack (any)
options (any)
Static Members
fromAuthUri(appInfo, authUri, networkStateCallBack, options, initialisation)
Instance Members
auth
crypto
cipherOpt
immutableData
mutableData
webFetch(url)
connection
networkState
appInfo
logPath(logFilename)
reconnect()

CryptoInterface

src/api/crypto.js

Encryption functionality for the app

Access it through your {SAFEApp} instance under app.crypto

new CryptoInterface(app: any)
Parameters
app (any)
Instance Members
sha3Hash(inpt)
getAppPubSignKey()
getAppPubEncKey()
generateEncKeyPair()
generateEncKeyPairFromRaw(rawPublicKey, rawSecretkey)
getSignKeyFromRaw(raw)
pubEncKeyKeyFromRaw(raw)
secEncKeyKeyFromRaw(raw)
generateNonce()

AuthInterface

src/api/auth.js

The AuthInterface contains all authentication related functionality with the network. Like creating an authenticated or unauthenticated connection or create messages for the IPC authentitcation protocol.

Access your instance through ypur {SAFEApp} instance under .auth.

new AuthInterface(app: any)
Parameters
app (any)
Instance Members
registered
genAuthUri(permissions, opts?)
genShareMDataUri(permissions)
genConnUri()
openUri(uri)
genContainerAuthUri(containers)
refreshContainersPermissions()
getContainersPermissions()
getOwnContainer()
canAccessContainer(name, permissions)
getContainer(name)
loginFromURI(responseUri)
loginForTest(access)

CipherOptInterface

src/api/cipher_opt.js

Provide the Cipher Opt API

new CipherOptInterface(app: any)
Parameters
app (any)
Instance Members
newPlainText()
newSymmetric()
newAsymmetric(key)

ImmutableDataInterface

src/api/immutable.js

Interact with Immutable Data of the Network through this Interface.

Access it through your {SAFEApp} instance under app.immutableData

new ImmutableDataInterface(app: any)
Parameters
app (any)
Instance Members
create()
fetch(address)

MutableDataInterface

src/api/mutable.js

Provide the MutableData API for the session.

Access via mutableData on your app Instance.

new MutableDataInterface(app: any)
Parameters
app (any)
Example
// using mutable Data
app.mutableData.newRandomPublic(15001)
  // set it up with starting data
  .then((mdata) => mdata.quickSetup({keyA: 'input value'})
   .then(() => mdata.getNameAndTag())) // return name and tag

// now read using name and tag
.then((ref) => app.mutableData.newPublic(ref.name, ref.tag)
  .then((mdata) => mdata.get('keyA').then((val) => {
    should(val.buf.toString()).equal('input value');
  })))
Instance Members
newRandomPrivate(typeTag)
newRandomPublic(typeTag)
newPrivate(name, typeTag, secKey, nonce)
newPublic(name, typeTag)
newPermissions()
newPermissionSet()
newMutation()
newEntries()
fromSerial(serial)

Immutable

Hold the connection to read an existing ImmutableData

new Reader()

Extends helpers.NetworkObject

Instance Members
read(options?)
size()

Holds a immutable Data Writer

new Writer()

Extends helpers.NetworkObject

Example
// write new data to the network
app.immutableData.create().then((writer)=> {
 return writer.write("some string\n")
  .then(() => writer.write("second string"))
  .then(() => writer.close())
  .then((address) => app.immutableData.fetch(address)
    .then((reader) => reader.read()
      .then( (payload) => {
        should(payload).equals("some string\nsecond string");
      })
    ))
})
Instance Members
write(string)
close(cipherOpt, the)
save()

Mutable

Holds the reference to a MutableData

new MutableData()

Extends h.NetworkObject

Instance Members
quickSetup(data, name, description)
setMetadata(name, description)
encryptKey(key)
encryptValue(value)
decrypt(value)
getNameAndTag()
getVersion()
get(key)
put(permissions, entries)
getEntries()
getKeys()
getValues()
getPermissions()
getUserPermissions(signKey)
delUserPermissions(signKey, version)
setUserPermissions(signKey, pmset, version)
applyEntriesMutation(mutations)
serialise()
emulateAs(eml)

Represent the Entries of a MutableData network object

new Entries()

Extends h.NetworkObject

Instance Members
len()
get(keyName)
forEach(fn)
insert(keyName, value)
mutate()

Represent the keys of a MutableData network object

new Keys()

Extends h.NetworkObject

Instance Members
len()
forEach(fn)

Represent the values of a MutableData network object

new Values()

Extends h.NetworkObject

Instance Members
len()
forEach(fn)

EntryMutationTransaction

src/api/mutable.js

Holds a mutations to be done to the entries within one transaction on the network.

You need this whenever you want to change the content of the entries.

new EntryMutationTransaction()

Extends h.NetworkObject

Example
// Mutate a range of Entries

app.mutableData.newPublic(somename, tagtype)
 .then((mData) => mData.getEntries()
  .then((entries) => entries.mutate()
    .then((m) => m.insert('key', 'value')
      // this is where all mutations are recorded
      .then(() => mData.applyEntriesMutation(m))
    )))
Instance Members
insert(keyName, value)
remove(keyName, version)
update(keyName, value, version)

One of: Insert, Update, Delete, ManagePermissions

MDataAction

Type: String

Holds the permissions of a MutableData object

new Permissions()

Extends h.NetworkObject

Instance Members
len()
getPermissionSet(signKey)
insertPermissionSet(signKey, permissionSet, pmset)
forEach(fn)

PermissionsSet

src/api/mutable.js

A Set of Permissions per Sign key. Each action might either be allowed or denied

new PermissionsSet()

Extends h.NetworkObject

Instance Members
setAllow(action)
setDeny(action)
clear(action)

Emulations

Emulations and Abstractions on top of MData

NFS Emulation on top of an MData

new NFS(mData: any)
Parameters
mData (any)
Instance Members
create(content)
fetch(fileName)
insert(fileName, file)
update(fileName, file, version)
delete(fileName, version)
open(file, openMode)

A NFS-style File

Note: As this application layer, the network does not check any of the metadata provided.

new File(ref: any, connection: any, fileCtx: any)
Parameters
ref (any)
connection (any)
fileCtx (any)
Instance Members
dataMapName
created
modified
size()
read(position, len)
write(fileContent, content)
close()
version

Types

Holds signature key

new SignKey()

Extends h.NetworkObject

Instance Members
getRaw()

Holds an asymmetric keypair

new KeyPair(app: any, pub: any, secret: any)
Parameters
app (any)
pub (any)
secret (any)
Instance Members
pubEncKey
secEncKey
decryptSealed(cipher)

Holds the secret part of an encryption key

new SecEncKey()

Extends h.NetworkObject

Instance Members
getRaw()
decrypt(cipher, theirPubKey)

Holds the public part of an encryption key

new PubEncKey()

Extends h.NetworkObject

Instance Members
getRaw()
encryptSealed(str)
encrypt(str, secretKey)

Holds the reference to a Cipher Options, either PlainText, Symmetric or Asymmetric

new CipherOpt()

Extends h.NetworkObject

NameAndTag

Type: Object

Parameters
name (Buffer) the XoR-name/address on the network
tag (Number) the type tag
ValueVersion

Type: Object

Parameters
buf (Buffer) the buffer with the value
version (Number) the version Holds the informatation of a value of a MutableData

Emulations are abstraction helpers on top of MData

Emulation

Type: NFS