Seald: documentation

# @seald-io/sdk-plugin-ssks-2mr

This module is a plugin for the Seald SDK : @seald-io/sdk (opens new window).

The @seald-io/sdk-plugin-ssks-2mr (opens new window) module allows to use the SSKS key storage service to store Seald identities easily and securely, encrypted by a key stored on your back-end server.

This module exposes a function, that takes keyStorageURL as argument, and returns a SDKPlugin which can be passed to the SealdSDK constructor.

When the Seald SDK is passed this plugin, the SealdSDK instance is modified to have a ssks2MR property, which exposes the SSKS2MR interface.

To use this plugin, your back-end server must first create an SSKS identity for the user in question by giving their email address or phone number. Also, the server has to generate a secure random secret key (called "twoManRuleKey") for the user.

After that, before each use of this plugin, your back-end server must start an SSKS session for the user. The server responds with a session_id and with a boolean must_authenticate.

If there has never been an identity stored on SSKS for this user, the server responds with must_authenticate to false. In that case, you can directly call saveIdentity with no challenge.

Otherwise, the user then receives an email or an SMS, containing a challenge, and this plugin can use the sessionId, the twoManRuleKey, and the challenge to store or retrieve their Seald identity on SSKS.

If the identity has been stored without no challenge, the first time the identity is retrieved afterwards, the keys of the identity in question are automatically renewed and stored again onto SSKS. If the same identity is also stored elsewhere (for example with @seald-io/sdk-plugin-ssks-password), you will have to save it again.

It is recommended not to retrieve the same identity with ssks2MR.retrieveIdentity on multiple devices at the same time, at the same exact instant, for example during automated tests. Please wait until one of the devices has finished retrieving the identity before starting the retrieval on another device.

You can find more information about the SSKS API for your back-end server here.

Example:

import SealdSDK from '@seald-io/sdk'
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr'

const seald = SealdSDK({
  appId,
  apiURL,
  plugins: [SealdSDKPluginSSKS2MR(keyStorageURL)] // passing the plugin to SealdSDK
})
await seald.initialize()

// Creating a Seald identity
await seald.initiateIdentity({ userId, userLicenseToken })
// The SealdSDK instance now has a `ssks2MR` property : we can use `saveIdentity`
await seald.ssks2MR.saveIdentity({ userId, sessionId, authFactor: { type: 'EM', value: emailAdress}, twoManRuleKey }) // `twoManRuleKey` is the secret key stored by your app's back-end to secure this user's identity

# Table of contents

# Interfaces

# Type Aliases

# Functions

# Type Aliases

# AuthFactor

Ƭ AuthFactor: Object

Authentication factor to which the challenge will be sent.

The value can either be an email address or a phone number, with the type set accordingly

# Type declaration

Name Type
type AuthFactorType
value string

# AuthFactorType

Ƭ AuthFactorType: "EM" | "SMS"

Type of authentication factor

'EM' if the associated value is an email address

'SMS' if the associated value is a phone number

# KeyStore2MR

Ƭ KeyStore2MR: Object

Internal interface to the SSKS two-man rule API.

WARNING: Do not use directly.

# Type declaration

Name Type
challengeValidate (args: { authFactor: AuthFactor ; challenge: string ; sessionId: string }) => Promise<{ newSessionId: string }>
extraHeaders Record<string, string>
push (args: { appId?: string ; authFactor: AuthFactor ; data: Buffer ; rawTwoManRuleKey?: string ; sessionId: string ; twoManRuleKey?: string ; userId?: string }) => Promise<void>
search (args: { appId?: string ; rawTwoManRuleKey?: string ; sessionId: string ; twoManRuleKey?: string ; userId?: string }) => Promise<{ authenticated: boolean ; data: Buffer }>

# Functions

# default

▸ default(keyStorageURL?): SDKPlugin

# Parameters

Name Type Default value Description
keyStorageURL string 'https://ssks.seald.io/' Optional. URL of the SSKS server to use. Defaults to 'https://ssks.seald.io/'

# Returns

SDKPlugin

← Interface: SSKS2MR →