# API Reference

# Seald SDK constructor function interface

SealdSDK(args: object): SealdSDK

Instantiate the Seald SDK.

Parameters:

args: object

Name Type Default Description
appId string - ID of your app.
apiURL? string "https://api.seald.io/" URL of the Seald API Servers to which it should connect.
hairlessURL? string "https://decrypt.seald.io/" URL of the Seald external decryption interface with which non-Seald users can decrypt documents.
keyStorageURL? string "https://ssks.seald.io/" URL of the SSKS Identity Key Storage to which it should connect.
nedbClient? NedbClient - Override the Nedb-compatible Database where the Seald instance stores its data. Defaults to an in-memory database.

Returns: SealdSDK


# SealdSDK

# Properties

# Methods

# apiURL

apiURL: string

apiURL with which this SealdSDK instance was created. URL of the Seald API Servers to which it should connect.


# appId

appId: string

appId with which this SealdSDK instance was created.


# eventBus

eventBus: Emittery

Event bus. See https://github.com/sindresorhus/emittery


# goatee

goatee: GoateeApi

Full Goatee library. For advanced use. See Goatee documentation, ask Seald Team.


# hairlessURL

hairlessURL: string

hairlessURL with which this SealdSDK instance was created. URL of the Seald external decryption interface with which non-Seald users can decrypt documents.


# intervals

intervals: object

Directly exposing the functions called periodically by "startIntervals". These functions cannot throw, so they are safe to "fire and forget": it's not necessary to await them.

# Type declaration:

  • checkMissingKeys(): Promise‹void›

  • heartbeat(): Promise‹void›

  • registerEventHandlers(): void

  • updateEvents(): Promise‹void›


# keyStorageURL

keyStorageURL: string

keyStorageURL with which this SealdSDK instance was created. URL of the SSKS Identity Key Storage to which it should connect.


# sscrypto

sscrypto: SSCrypto

Full SSCrypto library. For advanced use. See SSCrypto documentation at https://github.com/seald/sscrypto


# ssks

ssks: KeyStore

Manual SSKS Identity Key Storage interface. For advanced use.


# utils

utils: object

Various utilities, for advanced use.

# Type declaration:

  • encodePassword(password: string): Buffer

  • generateUserLicenseToken(userId: string, domainValidationKey: string, domainValidationKeyId: string): Promise‹string›

  • getRecipients(recipients: Recipients): Promise‹object›

  • parseUserLicenseToken(userLicenseToken: string): object

    • domainValidationKeyId: string

    • nonce: string

    • token: string

  • scrypt(buff: Buffer, salt: Buffer): Promise‹Buffer›

# addMissingKeys

addMissingKeys(deviceId: string, __namedParameters?: object): void

Trigger the re-encryption of missing message keys for the given deviceId. This function does not return a promise. It only triggers the re-encryption. To be notified of the end of the re-encryption, you must wait for the 'addMissingKeys-done' event on the event-bus. For example: const { deviceId, failed, done, error: null } = await sdk.eventBus.once('addMissingKeys-done')

Parameters:

deviceId: string

Optional __namedParameters: object

Name Type Description
nRetries number How many times to retry. Defaults to 3.
waitBetweenRetries number Time to wait between retries in milliseconds. Defaults to 30 seconds.

Returns: void


# createEncryptionSession

createEncryptionSession(recipients: Recipients, opts?: object): Promise‹EncryptionSession›

Create an encryption session, with which you can then encrypt / decrypt multiple messages.

Parameters:

recipients: Recipients

Recipients for whom to encrypt.

Optional opts: object

Name Type
metadata? string
selfDestructDate? string

Returns: Promise‹EncryptionSession›


# createSubIdentity

createSubIdentity(deviceName?: string): Promise‹object›

Create a sub-identity for the current identity, for example to use on another device. The created sub-identity Buffer can then be imported into another SDK instance using sdk.importIdentity.

A re-encryption of existing message keys must happen, so the new sub-identity will be able to decrypt existing messages for this account:

  • If you have called startIntervals, the re-encryption will be triggered automatically.
  • Otherwise, you must trigger addMissingKeys with the newly created deviceId, in order for the re-encryption to happen.

Parameters:

Name Type Description
deviceName? string Name of the new device.

Returns: Promise‹{ deviceId: string, identity: Buffer }›


# decryptFile

decryptFileT›(encryptedFile: T): Promise‹T›

Decrypt an encrypted file.

Type parameters:

T: string | Buffer | Blob

Parameters:

Name Type Description
encryptedFile T File to decrypt. Can be either a binary string, a Blob, or a Buffer. The function will return the decrypted file in same format.

Returns: Promise‹T›


# encryptFile

encryptFileT›(clearFile: T, filename: string, recipients: Recipients, opts?: object): Promise‹T›

Encrypt a file.

example

// Encrypt a string for another user of the app
const encryptedString = await seald.encryptFile(
  'Secret file content',
  'SecretFile.txt',
  { userIds: ['Other-User'] }
)

// Encrypt a Buffer for a Seald user
const encryptedBuffer = await seald.encryptFile(
  Buffer.from('Secret file content'),
  'SecretFile.txt',
  { sealdIds: [otherUserSealdId] }
)

// Encrypt a Blob for an external user
const encryptedBlob = await seald.encryptFile(
  new Blob(['Secret file content']),
  'SecretFile.txt',
  { emails: ['external@domain.com'] }
)

Type parameters:

T: string | Buffer | Blob

Parameters:

clearFile: T

File to encrypt. Can be either a binary string, a Blob, or a Buffer. The function will return the encrypted file in same format.

filename: string

Name of the file

recipients: Recipients

Recipients for whom to encrypt

Optional opts: object

Name Type
allowDownload? boolean
selfDestructDate? string

Returns: Promise‹T›


# exportIdentity

exportIdentity(): Promise‹Buffer›

Export the current identity, to handle it manually

Returns: Promise‹Buffer›


# importIdentity

importIdentity(identity: Buffer): Promise‹void›

Import identity manually

Parameters:

Name Type
identity Buffer

Returns: Promise‹void›


# initialize

initialize(): Promise‹void›

Initialize the SDK. Must be called before any other method. Resolves when the initialization is done, and you can use the Seald SDK. Afterwards, you should either create or retrieve an identity first.

Returns: Promise‹void›


# initiateIdentity

initiateIdentity(args: object): Promise‹void›

Create the account for the first time.

Parameters:

args: object

Name Type Description
exportToSSKS? boolean Whether or not to export the created identity to SSKS, for later retrieval. Defaults to true.
password? string The user's password. It will be used to encrypt the stored identity keys. Required if exportToSSKS is enabled.
userId string The unique ID of the current user inside your app. It will be used to identify this user.
userLicenseToken string The license token to allow the current user to join your app's Seald Team. Can be generated by your server (safer), or with generateUserLicenseToken.

Returns: Promise‹void›


# registrationStatus

registrationStatus(): Promise‹"no-account" | "no-display-name" | "no-email" | "email-to-validate" | "no-team" | "registered"›

Returns the registration status of the SDK instance.

Returns: Promise‹"no-account" | "no-display-name" | "no-email" | "email-to-validate" | "no-team" | "registered"›


# retrieveEncryptionSession

retrieveEncryptionSession(args: object): Promise‹EncryptionSession›

Retrieve an encryption session, with which you can then encrypt / decrypt multiple messages, either with an encrypted message of this session, or with the sessionId.

Parameters:

args: object

Name Type
encryptedMessage? string
sessionId? string

Returns: Promise‹EncryptionSession›


# retrieveIdentity

retrieveIdentity(__namedParameters: object): Promise‹void›

Retrieve the Seald account previously created with initiateIdentity.

Parameters:

__namedParameters: object

Name Type
password string
userId string

Returns: Promise‹void›


# changeIdentityPassword

changeIdentityPassword(__namedParameters: object): Promise‹void›

Change the password of a Seald account.

Parameters:

__namedParameters: object

Name Type
currentPassword string
newPassword string
userId string

Returns: Promise‹void›


# startIntervals

startIntervals(): Promise‹void›

Call the functions in "intervals", then setup intervals so they are called periodically. This function cannot throw, so it is safe to "fire and forget": it's not necessary to await it.

Returns: Promise‹void›


# stopIntervals

stopIntervals(): void

Stop calling the functions in "intervals" periodically.

Returns: void

# EncryptionSession

# Properties

# Methods

# sessionId

sessionId: string

The sessionId for this EncryptionSession instance.

# addRecipients

addRecipients(recipients: Recipients): Promise‹AuthorizeRecipientResult

Add new recipients to this session. These recipients will be able to read all encrypted message of this session.

Parameters:

Name Type
recipients Recipients

Returns: Promise‹AuthorizeRecipientResult


# decrypt

decrypt(encryptedText: string): Promise‹string›

Decrypts an encrypted message string into the corresponding clear-text string.

Parameters:

Name Type
encryptedText string

Returns: Promise‹string›


# encrypt

encrypt(clearText: string): Promise‹string›

Encrypts a clear-text string into an encrypted message, for the recipients of this session.

Parameters:

Name Type
clearText string

Returns: Promise‹string›


# revoke

revoke(): Promise‹RevokeResult

Entirely revoke this session. You can only do it if you are this session's administrator.

Returns: Promise‹RevokeResult


# revokeRecipients

revokeRecipients(recipients: Recipients): Promise‹RevokeResult

Revoke recipients from this session. You can only do it if you added these recipients yourself, or if you are this session's administrator.

Parameters:

Name Type
recipients Recipients

Returns: Promise‹RevokeResult

# Helper Types

# Recipients

Ƭ Recipients: object

# Type declaration:

  • APConnectors? : Array‹string›

  • emails? : Array‹string›

  • sealdIds? : Array‹string›

  • userIds? : Array‹string›


# KeyStore

Ƭ KeyStore: object

# Type declaration:

  • push(): function

    • (appId: string, userId: string, password: string, data: Buffer): Promise‹void›
  • search(): function

    • (appId: string, userId: string, password: string): Promise‹Buffer›

# AuthorizeRecipientResult

Ƭ AuthorizeRecipientResult: object

# Type declaration:

  • addedHairlessRecipients(): object

  • addedRecipients(): object

    • status(): object

# RevokeResult

Ƭ RevokeResult: object

userIDs is of the form { 'sealdId': 'ok'|'ko' }.

entrustedEmails is of the form { 'email@domain.com': 'ok'|'ko' }.

# Type declaration:

  • entrustedEmails(): object

  • revokeAll(): object

    • entrustedEmails(): object

    • userIDs(): object

  • userIDs(): object