# Interface: SealdSDK

# Table of contents

# Properties

# Methods

# Properties

# 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<Record<string, any>, Record<string, any> & OmnipresentEventData, string>

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


# goatee

goatee: any

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

Name Type
checkMissingKeys () => Promise<void>
heartbeat () => Promise<void>
registerEventHandlers () => void
updateEvents () => Promise<void>

# sscrypto

sscrypto: SSCrypto

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


# utils

utils: Object

Various utilities, for advanced use.

# Type declaration

Name Type Description
fetch FetchFunction The fetch implementation used by this SDK instance For advanced use.
scrypt SCrypt SCrypt wrapper with reasonable parameters. For advanced use.
encodePassword (password: string) => Buffer -
generateUserLicenseToken (userId: string, domainValidationKey: string, domainValidationKeyId: string) => Promise<string> -
getRecipients (recipients: Recipients) => Promise<Object> -
parseUserLicenseToken (userLicenseToken: string) => { domainValidationKeyId: string ; nonce: string ; token: string } -

# Methods

# addGroupMembers

addGroupMembers(groupId, newMembers): Promise<void>

Add members to a group. Can only be done by a group administrator.

# Parameters

Name Type Description
groupId string id of the group
newMembers Recipients id of members to add

# Returns

Promise<void>


# addMissingKeys

addMissingKeys(deviceId, retryOptions?): 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

Name Type Description
deviceId string
retryOptions? Object Optional.
retryOptions.nRetries? number Optional. How many times to retry. Defaults to 3.
retryOptions.waitBetweenRetries? number Optional. Time to wait between retries in milliseconds. Defaults to 30000ms = 30 seconds.

# Returns

void


# checkGroupSelfAddSecret

checkGroupSelfAddSecret(groupId): Promise<boolean>

Check if a self-add secret is set for a given group. Only accessible to group admins.

# Parameters

Name Type
groupId string

# Returns

Promise<boolean>


# checkSigchainHash

checkSigchainHash(recipient, sigchainHash): Promise<"OK">

Verifiy recipient sigchain hash. Throw if the hash is incorrect

# Parameters

Name Type
recipient Recipients
sigchainHash string

# Returns

Promise<"OK">


# createEncryptionSession

createEncryptionSession(recipients, opts?): Promise<EncryptionSession>

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

# Parameters

Name Type Description
recipients Recipients Recipients for whom to encrypt.
opts? Object Optional.
opts.encryptForSelf? boolean -
opts.metadata? string Optional. Arbitrary metadata string, for later reference.
opts.selfDestructDate? string -

# Returns

Promise<EncryptionSession>


# createGroup

createGroup(args): Promise<Object>

Create a group

# Parameters

Name Type Description
args Object
args.admins Recipients Administrators of the group. Administrators must also be members. It must include yourself.
args.customGroupSymKey? string Optional. For advanced use. Set a custom group SymKey manually. Do not use both customGroupSymKey and selfAddPassword, as selfAddPassword is automatically derived into customGroupSymKey. Useful if you want to pass it out-of-band to other users to use the self-add. Should be 512 bits (64 bytes) of cryptographically secure random, encoded as Base64.
args.groupName string Group name
args.members Recipients Members of the group. It must include yourself.
args.selfAddPassword? string Optional. Pass this if you want to enable self-add to this group. Derived automatically to a selfAddSecret and a customGroupSymKey. The same selfAddPassword must be used for all operations, and will be automatically derived into both groupSymKey and groupSelfAddSecret when necessary. Useful if you want to pass it out-of-band to other users to use the self-add.
args.selfAddSecret? string Optional. For advanced use. Set a self-add secret manually. Do not use both selfAddSecret and selfAddPassword, as selfAddPassword is automatically derived into selfAddSecret.

# Returns

Promise<Object>

}


# createSubIdentity

createSubIdentity(deviceName?): 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 Optional. Name of the new device.

# Returns

Promise<Object>

}


# decryptFile

decryptFile<T>(encryptedFile): Promise<T>

Decrypt an encrypted file.

# Type parameters

Name Type
T extends string | Buffer | Blob | ReadableStream<any> | Readable

# 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>


# decryptMessage

decryptMessage(clearText): Promise<string>

Decrypt a message.

# Parameters

Name Type
clearText string

# Returns

Promise<string>


# deleteGroup

deleteGroup(groupId): Promise<void>

Delete a group

# Parameters

Name Type
groupId string

# Returns

Promise<void>


# encryptFile

encryptFile<T>(clearFile, filename, recipients, opts?): 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

Name Type
T extends string | Buffer | Blob | ReadableStream<any> | Readable

# Parameters

Name Type Description
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
opts? Object -
opts.allowDownload? boolean Optional. Whether or not to allow non-seald external recipients to download a clear version of the file
opts.encryptForSelf? boolean -
opts.fileSize? number Optional. Size of the file to encrypt. Must be specified for ReadableStream and NodeReadable
opts.metadata? string Optional. Arbitrary metadata string, not encrypted, for later reference. Takes filename as default value, use '' to override.
opts.selfDestructDate? string Optional. Date at which the encrypted file should be automatically revoked. Format: 'YYYY-MM-DD'.

# Returns

Promise<T>


# encryptMessage

encryptMessage(clearText, recipients, opts?): Promise<string>

Encrypt a message.

# Parameters

Name Type Description
clearText string
recipients Recipients
opts? Object Optional.
opts.encryptForSelf? boolean -
opts.metadata? string Optional. Arbitrary metadata string, for later reference.
opts.selfDestructDate? string Optional. Date at which the encrypted file should be automatically revoked. Format: 'YYYY-MM-DD'.

# Returns

Promise<string>


# exportIdentity

exportIdentity(): Promise<Buffer>

Export the current identity, to handle it manually

# Returns

Promise<Buffer>


# getRSAKeyPromise

getRSAKeyPromise(): Promise<string>

Function which create a promise that resolves to a newly generated b64 encoded RSA key.

# Returns

Promise<string>


# getSigchainHash

getSigchainHash(recipient?): Promise<string>

Get hash of a user last sigchain transaction If no recipient is given, return the current user hash.

# Parameters

Name Type
recipient? Recipients

# Returns

Promise<string>


# importIdentity

importIdentity(identity): 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. If you use a persistent DB and do not know the registration status for certain, you may want to run sdk.registrationStatus after initialize, to check if you are in the 'no-account' or 'registered' state.

# Returns

Promise<void>


# initiateIdentity

initiateIdentity(args): Promise<void>

Create the account for the first time.

# Parameters

Name Type Description
args Object
args.userId string The unique ID of the current user inside your app. It will be used to identify this user.
args.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>


# listBackupKeys

listBackupKeys(acceptBackupKeys?): Promise<{ created: Date ; createdBy: string ; id: string ; name: string ; publicKey: PublicKey }[]>

List admin backup keys

# Parameters

Name Type
acceptBackupKeys? boolean

# Returns

Promise<{ created: Date ; createdBy: string ; id: string ; name: string ; publicKey: PublicKey }[]>


# listGroupMembers

listGroupMembers(groupId): Promise<{ displayName: string ; id: string ; isAdmin: boolean }[]>

List members of a group

# Parameters

Name Type
groupId string

# Returns

Promise<{ displayName: string ; id: string ; isAdmin: boolean }[]>

}


# listGroups

listGroups(args?): Promise<Object>

List all groups in team

# Parameters

Name Type Description
args? Object Optional.
args.all? boolean Optional. Return all pages at once.
args.mine? boolean Optional. Show only groups of which the current user is a member
args.page? number Optional.

# Returns

Promise<Object>

{Promise<{ lastPage: number, results: Array<{ created: string, deviceId: string, bearduser: { id: string, displayName: string deviceId: string} }>

}


# registrationStatus

registrationStatus(): Promise<"no-account" | "no-team" | "registered">

Returns the registration status of the SDK instance. In the SDK, you should only get the values 'no-account' or 'registered'.

# Returns

Promise<"no-account" | "no-team" | "registered">


# removeGroupMembers

removeGroupMembers(groupId, membersToRemove): Promise<void>

Remove members from a group. Can only be done by a group administrator. You should call renewGroupKey after this.

# Parameters

Name Type Description
groupId string id of the group
membersToRemove Recipients id of members to add

# Returns

Promise<void>


# renewGroupKey

renewGroupKey(groupId, options?): Promise<void>

Renew group private key. Should be called after removing members.

# Parameters

Name Type Description
groupId string id of the group
options? Object
options.customGroupSymKey? string Optional. For advanced use. Set a custom group SymKey manually. Do not use both customGroupSymKey and selfAddPassword, as selfAddPassword is automatically derived into customGroupSymKey. Useful if you want to pass it out-of-band to other users to use the self-add. Should be 512 bits (64 bytes) of cryptographically secure random, encoded as Base64. MUST be the same as the one used during the group creation.
options.selfAddPassword? string Optional. Derived automatically to a customGroupSymKey. The same selfAddPassword must be used for all operations, and will be automatically derived into both groupSymKey and groupSelfAddSecret when necessary. Useful if you want to pass it out-of-band to other users to use the self-add. MUST be the same as the one used during the group creation.

# Returns

Promise<void>


# renewKey

renewKey(): Promise<void>

Renew the key of this Identity. Be careful, if this Identity is stored on SSKS or with another plugin, you will have to store it again, as the old one will not be valid anymore.

# Returns

Promise<void>


# retrieveEncryptionSession

retrieveEncryptionSession(args): 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

Name Type Description
args Object Optional.
args.encryptedMessage? string Optional. Arbitrary encrypted message from the session to retrieve.
args.sessionId? string Optional. sessionId of the session to retrieve.

# Returns

Promise<EncryptionSession>


# selfAddGroup

selfAddGroup(groupId, args): Promise<void>

Add self to a group with a self-add secret.

# Parameters

Name Type Description
groupId string
args Object Optional.
args.groupSymKey? string Optional. For advanced use. Set a custom group SymKey manually. Do not use both customGroupSymKey and selfAddPassword, as selfAddPassword is automatically derived into customGroupSymKey. Useful if you want to pass it out-of-band to other users to use the self-add. Should be 512 bits (64 bytes) of cryptographically secure random, encoded as Base64. MUST be the same as the one used during the group creation, and during every group keys renewal.
args.selfAddPassword? string Optional. Derived automatically to a selfAddSecret. The same selfAddPassword must be used for all operations, and will be automatically derived into both groupSymKey and groupSelfAddSecret when necessary. MUST be the same as the one used during the group creation.
args.selfAddSecret? string Optional. For advanced use. Pass a self-add secret manually. Do not use both selfAddSecret and selfAddPassword, as selfAddPassword is automatically derived into selfAddSecret.

# Returns

Promise<void>


# setGroupAdmin

setGroupAdmin(groupId, groupMember, statusToSet): Promise<void>

Set admin status of a group member. Can only be done one recipient at a time. Can only be done by a group administrator.

# Parameters

Name Type
groupId string
groupMember Recipients
statusToSet boolean

# Returns

Promise<void>


# setGroupSelfAddSecret

setGroupSelfAddSecret(groupId, args): Promise<boolean>

Set or change a self-add secret for a given group. Set selfAddSecret to null to disable. You must pass either a selfAddSecret, or a selfAddPassword that will be derived into one. Only accessible to group admins.

# Parameters

Name Type Description
groupId string
args Object Optional.
args.selfAddPassword? string Optional. Derived automatically to a selfAddSecret. The same selfAddPassword must be used for all operations, and will be automatically derived into both groupSymKey and groupSelfAddSecret when necessary. MUST be the same as the one used during the group creation.
args.selfAddSecret? string Optional. Set to null to disable self-add for this group. Non-null values are for advanced use, to manually set a self-add secret. Do not use both selfAddSecret and selfAddPassword, as selfAddPassword is automatically derived into selfAddSecret.

# Returns

Promise<boolean>


# 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