# Security: Token & Authentication

App front-end and back-end secure communication specifications.

The front-end RESTful API and WebSocket (socket.io, synctable...) must use EdgerOS standard security specifications, otherwise these operations will be intercepted by EdgerOS.

# RESTful

Developers need to ensure that any REST services that need to be protected must start with /api/, such as /api/query and when calling these REST services, they need to ensure that the header contains the 'edger-token', 'edger-srand' fields.

fetch('/api/...', {
  ...
  headers: {
    'edger-token': ...,
    'edger-srand': ...
  },
  ...
}).then(...).catch(...);

# WebSocket

The developer must ensure that the WebSocket URL contains the 'edger-token' and 'edger-srand' query parts. socket.io module can use query option:

io.connect('/path', {
  query: 'edger-token=...&edger-srand=...'
});

synctable module can use query option:

const t = new SyncTable(server, 't', {
  token: ...,
  srand: ...
});

# Functions

# edger.token()

• Returns: {Promise} Promise object.

Actively obtain the token and srand information needed for current communication. If successful, the data object contains the following fields:

• token {String} Communication token.
• srand {String} Communication random string.

# Example

edger.token().then(data => {
  const { token, srand } = data;
  console.log(token, srand);
}).catch(error => {
  console.error(error);
});

# async / await

async function token() {
  try {
    return await edger.token();
  } catch (error) {
    console.error(error);
  }
}

# edger.security.verify()

• Returns: {Promise} Promise object.

Before performing high-risk operations, the EdgerOS emergency password verification dialog box will pop up, and the user needs to enter the EdgerOS emergency password for verification, and the relevant operations can only be performed after the verification passed.

The data object contains the following field:

• success {Boolean} Indicate whether this API has been successfully called.

# Example

edger.security.verify()
  .then((data) => {
    // If data.success is true, the verification dialog pops up successfully
  })
  .catch((error) => {
    console.error(error)
  })

# async / await

async function verify() {
  try {
    return await edger.security.verify();
  } catch (error) {
    console.error(error);
  }
}

# Events

The unified event listener provided by Web-SDK:

const listener = (payload) => {
  // Event handling...
}

// add listener
edger.addEventListener('some-event', listener);

// or 
// onAction() is an alias of addEventListener().
edger.onAction('some-event', listener);

// remove listener
edger.removeEventListener('some-event', listener);

// remove all listeners
edger.removeAllListeners();

For security reasons, the elimination time of token and srand is very fast, so users must listen to the following event to quickly update token and srand.

# token

EdgerOS updates this App token and srand value.

# Example

const listener =  (payload) => {
  const { token, srand } = payload;
  console.log(token, srand);
}

edger.addEventListener('token', listener);

# verify

When the verification result is obtained, EdgerOS will send this event, and the developer needs to listen this event to obtain the verification result.

• event {Object} Event is the result of the verification.
  • action {String} Indicate the operation type of the verification component. There are two values: cancel and verify. When it is cancel, it means that the user has cancelled the verification. When it is verify, it means that the user has submitted verification.
  • result {Object} Indicate the result of the verification. Only included when the action is verify.
    • success {Boolean} Indicate whether the verification is passed, true means the verification is passed, false means the verification is not passed.
    • times {Number} Indicate how many times the password is verified.
    • wait {Number} Indicate the number of minutes to wait for the next verification.

# Example

const listener =  (payload) => {
   const { action, result } = payload;

  if (action === 'cancel') {
      console.log('Verification cancelled')
  } else if (action === 'verify') {
      if (result.success) {
          console.log('Verification passed');
      } else {
        console.log(`Tried ${result.times} times，need to wait for ${result.wait} minutes before trying again`);
      }
  }
}

edger.addEventListener('verify', listener);