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


# encryptionSessionCache

encryptionSessionCache: EncryptionSessionCache

Cache object to store encryption sessions


# encryptionSessionCacheTTL

encryptionSessionCacheTTL: number

The lifetime of encryptionSession cache.


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

# keySize

keySize: 1024 | 2048 | 4096

The configured key size for newly generated asymmetric keys.


# numberPreGeneratedIdentityKeys

numberPreGeneratedIdentityKeys: number

Get the number of pre-generated keys currently in the pool


# 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.
deserializeSession (serialized: string) => EncryptionSession Deserialize a serialized session. For advanced use.
encodePassword (password: string) => Buffer Normalize and encode a string password into a Buffer. For advanced use.
generateRegistrationJWT (JWTSharedSecret: string, JWTSharedSecretId: string, opts?: { joinTeam?: boolean ; userId?: string }) => Promise<string> Generate a registration JWT with the given Shared Secret. Optionally, add a userId to the registering user. Optionally, disable the joinTeam to only add userId. If joinTeam is set to false, this JWT will only be usable with sdk.pushJwt, not with sdk.initiateIdentity. This registration JWT is only usable once, and is only valid for 10 minutes.
generateUserLicenseToken (userId: string, domainValidationKey: string, domainValidationKeyId: string) => Promise<string> Generate a userLicenseToken for the given userId, with your app's secret domainValidationKey and your domainValidationKeyId.
getRecipients (recipients: Recipients, opts?: { allowUnregisteredUsers: boolean }) => Promise<{ hairlessRecipients: EntrustedRecipient[] ; recipients: string[] }> Manually parse a Recipients parameter into Seald and External recipients, into the format used internally by Goatee. For advanced use.
parseUserLicenseToken (userLicenseToken: string) => { domainValidationKeyId: string ; nonce: string ; token: string } Parse a given userLicenseToken. For advanced use.
retrieveEncryptionSessionId <T>(args: { encryptedFile?: T ; encryptedMessage?: string }) => Promise<string> Retrieve an encryption session id

# 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, opts?): Promise<{ lastPosition: number ; position: number }>

Verify if a hash is included in the recipient sigchain. Use the position option to check the hash of a specific sigchain transaction.

# Parameters

Name Type Description
recipient Recipients
sigchainHash string
opts? Object
opts.position? number position of the sigchain transaction against which to check the hash.

# Returns

Promise<{ lastPosition: number ; position: number }>

}


# close

close(): Promise<void>

Close the database. After this, this SDK instance will no longer be usable. This also calls `stopIntervals.

# Returns

Promise<void>


# 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 -
opts.allowDownload? boolean Optional. Whether or not to allow non-seald recipients with an email address to download a clear version of the file. Defaults to false.
opts.allowUnregisteredUsers? boolean Optional. Whether or not to allow non-seald, unregistered recipients. Defaults to false.
opts.encryptForSelf? boolean Optional. Whether or not to include the current account as recipient. Defaults to true
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'.
opts.useCache? boolean Whether or not to use the cache (if enabled globally). Default to true.

# Returns

Promise<EncryptionSession>


# createGroup

createGroup(args): Promise<{ groupName: string ; id: string }>

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<{ groupName: string ; id: string }>

}


# createSubIdentity

createSubIdentity(opts?): Promise<{ deviceId: string ; identity: Buffer }>

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 for the new sub-identity to be able to decrypt existing messages for this account:

  • If you do not pass any argument, or pass shouldReencrypt: true, it will happen automatically
  • Otherwise, you must trigger addMissingKeys with the newly created deviceId, in order for the re-encryption to happen.

# Parameters

Name Type Description
opts? Object Optional.
opts.deviceName? string Optional. Name of the new device.
opts.nRetries? number Optional. How many times to retry re-encryption. Defaults to 3.
opts.shouldReencrypt? boolean Optional. Should trigger the re-encryption of missing message keys for the newly created device. Defaults to true.
opts.waitBetweenRetries? number Optional. Time to wait between retries in milliseconds. Defaults to 30000ms = 30 seconds.

# Returns

Promise<{ deviceId: string ; identity: Buffer }>

}


# decryptFile

decryptFile<T>(encryptedFile, opts?): Promise<{ data: T ; filename: string ; sessionId: string ; size: number ; type: FileType }>

Decrypt an encrypted file.

# Type parameters

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

# 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.
opts? Object Optional.
opts.useCache? boolean Whether or not to use the cache (if enabled globally). Default to true.

# Returns

Promise<{ data: T ; filename: string ; sessionId: string ; size: number ; type: FileType }>

}


# decryptMessage

decryptMessage(encryptedString, opts?): Promise<string>

Decrypt a message.

# Parameters

Name Type Description
encryptedString string
opts? Object Optional.
opts.useCache? boolean Whether or not to use the cache (if enabled globally). Default to true.

# Returns

Promise<string>


# deleteGroup

deleteGroup(groupId): Promise<void>

Delete a group

# Parameters

Name Type
groupId string

# Returns

Promise<void>


# dropDatabase

dropDatabase(): Promise<void>

Drop local database. It will also reset the current SDK instance. Call initialize() or initiatIdentity() afterward to continue with this sealdSDK instance.

# 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 | Readable | Blob | ReadableStream<any>

# 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.allowUnregisteredUsers? boolean Optional. Whether or not to allow non-seald, unregistered recipients. Defaults to false.
opts.encryptForSelf? boolean Optional. Whether or not to include the current account as recipient. Defaults to true
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(clearString, recipients, opts?): Promise<string>

Encrypt a message.

# Parameters

Name Type Description
clearString string
recipients Recipients
opts? Object Optional.
opts.allowUnregisteredUsers? boolean Optional. Whether or not to allow non-seald, unregistered recipients. Defaults to false.
opts.encryptForSelf? boolean Optional. Whether or not to include the current account as recipient. Defaults to true
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>


# getCurrentAccountInfo

getCurrentAccountInfo(): Promise<{ deviceId: string ; sealdId: string ; userId: string }>

Get account info of current SDK instance

# Returns

Promise<{ deviceId: string ; sealdId: string ; userId: string }>

}


# getRSAKeyPromise

getRSAKeyPromise(size?): Promise<string>

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

# Parameters

Name Type
size? 1024 | 2048 | 4096

# Returns

Promise<string>


# getSigchainHash

getSigchainHash(recipient?, opts?): Promise<{ hash: string ; position: number }>

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

# Parameters

Name Type Description
recipient? Recipients
opts? Object
opts.position? number get the hash at the given position. Default to last transaction

# Returns

Promise<{ hash: string ; position: number }>


# importIdentity

importIdentity(identity): Promise<{ deviceId: string ; sealdId: string ; userId: string }>

Import identity manually

# Parameters

Name Type
identity Buffer

# Returns

Promise<{ deviceId: string ; sealdId: string ; userId: string }>

}


# 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<{ deviceId: string ; sealdId: string ; userId: string }>

Create the account for the first time.

# Parameters

Name Type Description
args Object
args.displayName? string Name to display this user under on the dashboard. Defaults to userId.
args.signupJWT? string JWT to allow the current user to join your app's Seald Team. Must be generated by your server.
args.userId? string The unique ID of the current user inside your app. It will be used to identify this user. Required if you use a userLicenseToken. Forbidden if you use a signupJWT.
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<{ deviceId: string ; sealdId: string ; userId: string }>

{Promise<{ userId: string, sealdId: string, deviceId: string }>}


# 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<{ lastPage: number ; results: { bearduser: { displayName: string ; id: string } ; created: string ; deviceId: string }[] }>

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<{ lastPage: number ; results: { bearduser: { displayName: string ; id: string } ; created: string ; deviceId: string }[] }>

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

}


# preGenerateIdentityKeys

preGenerateIdentityKeys(n?): void

Pre-generate identity keys and add them to the pool. Pre-generation is started for all keys as soon as this function is called. Keys are always added at the end of the pool, and used from the beginning of the pool.

# Parameters

Name Type Description
n? number Number of identity keys to pre-generate. Defaults to 1. Minimum 1. Maximum 10.

# Returns

void


# pullPreGeneratedIdentityKeyFromPool

pullPreGeneratedIdentityKeyFromPool(): PreGeneratedIdentityKey

Retrieve an identity key from the pool. If none are available, this will return null. Key is retrieved from the beginning of the pool.

# Returns

PreGeneratedIdentityKey


# pushJwt

pushJwt(jwt): Promise<{ joinedTeam: boolean ; userId?: string }>

Use a JWT on the current identity

# Parameters

Name Type Description
jwt string JWT to use. Must be generated by your server.

# Returns

Promise<{ joinedTeam: boolean ; userId?: string }>

{Promise<{ userId: string|null, joinedTeam: boolean }>}


# pushPreGeneratedIdentityKeyToPool

pushPreGeneratedIdentityKeyToPool(key): void

Add a previously retrieved identity key into the pool. Key is added at the end of the pool.

# Parameters

Name Type
key PreGeneratedIdentityKey

# Returns

void


# 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<T>(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.

# Type parameters

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

# Parameters

Name Type Description
args Object
args.encryptedFile? T Optional. Arbitrary encrypted file from the session to retrieve.
args.encryptedMessage? string Optional. Arbitrary encrypted message from the session to retrieve.
args.sessionId? string Optional. sessionId of the session to retrieve.
args.useCache? boolean Whether or not to use the cache (if enabled globally). Default to true.

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


# setLogLevel

setLogLevel(logLevel): void

This sets the log level. logLevel must be a string of value silly, debug, info, warn, error, none, or a template of the format ${namespace_1}:${logLevel_for_namespace_1},${namespace_2}:${logLevel_for_namespace_2},.... This will set the log level for all SDK and AnonymousSDK instances, not only the current one.

# Parameters

Name Type
logLevel string

# Returns

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


# updateContacts

updateContacts(r): Promise<void>

Update the local database for the specified recipients.

# Parameters

Name Type
r Recipients

# Returns

Promise<void>