Interface: SealdSDK
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
encryptionSessionCacheCleanupInterval
encryptionSessionCacheCleanupInterval:
number
The cleanup interval of encryptionSession cache.
encryptionSessionCacheTTL
encryptionSessionCacheTTL:
number
The lifetime of encryptionSession cache.
eventBus
eventBus:
Emittery<Record<PropertyKey,any>,Record<PropertyKey,any> &_OmnipresentEventData,DatalessEventNames<Record<PropertyKey,any>>>
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: {
checkMissingKeys:Promise<void>;heartbeat:Promise<void>; }
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.
checkMissingKeys()
Check if there are missing message keys for some of the current user's devices, and if so re-encrypts them.
Returns
Promise<void>
heartbeat()
Send a heartbeat to the server. Contrary to sdk.heartbeat(), this version of the heartbeat cannot throw: it will only print a warning in case of error.
Returns
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: {
fetch:FetchFunction;scrypt:SCrypt;cleanEncryptionSessionCache:Promise<void>;deserializeSession:EncryptionSession;encodePassword:Buffer<ArrayBufferLike>;generateB64EncodedSymKey:Promise<string>;getRecipients:Promise<{hairlessRecipients:EntrustedRecipient[];recipients:string[];rights:Record<string,UserRights>; }>;parseUserLicenseToken: {domainValidationKeyId:string;nonce:string;token:string; };readKeyBackup:Promise<Buffer<ArrayBufferLike>>;retrieveEncryptionSessionId:Promise<string>;writeKeyBackup:Promise<void>; }
Various utilities, for advanced use.
fetch
fetch:
FetchFunction
The fetch implementation used by this SDK instance For advanced use.
scrypt
scrypt:
SCrypt
SCrypt wrapper with reasonable parameters. For advanced use.
cleanEncryptionSessionCache()
Cleans the encryption session cache of entries with expired lifetime.
Returns
Promise<void>
deserializeSession()
Deserialize a serialized session. For advanced use.
Parameters
serialized
string
Returns
EncryptionSession
encodePassword()
Normalize and encode a string password into a Buffer. For advanced use.
Parameters
password
string
Returns
Buffer<ArrayBufferLike>
generateB64EncodedSymKey()
Generate a symmetric key, and return it as a Base64 encoded string.
The key generate here can then be used as databaseRawKey when instantiating the SDK, as rawOverEncryptionKey when creating TMR accesses, as rawSymKey when adding SymEncKey accesses, or as rawTwoManRuleKey in the ssks2MR plugin.
Returns
Promise<string>
getRecipients()
Manually parse a Recipients parameter into Seald and External recipients, as well as rights, into the format used internally by Goatee. For advanced use.
Parameters
recipients
opts?
allowUnregisteredUsers
boolean
Optional. Whether or not to allow non-seald, unregistered recipients. Defaults to false.
Returns
Promise<{hairlessRecipients: EntrustedRecipient[];recipients: string[];rights: Record<string, UserRights>; }>
hairlessRecipients
hairlessRecipients:
EntrustedRecipient[]
recipients
recipients:
string[]
rights
rights:
Record<string,UserRights>
parseUserLicenseToken()
Parse a given userLicenseToken. For advanced use.
Parameters
userLicenseToken
string
Returns
{domainValidationKeyId: string;nonce: string;token: string; }
domainValidationKeyId
domainValidationKeyId:
string
nonce
nonce:
string
token
token:
string
readKeyBackup()
Read the internal key backup. For advanced use.
Returns
Promise<Buffer<ArrayBufferLike>>
retrieveEncryptionSessionId()
Retrieve an encryption session id
Type Parameters
• T extends string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob | ReadableStream<any> | Readable | Buffer<ArrayBufferLike>
Parameters
args
encryptedFile
T
Optional. Arbitrary encrypted file from the session to retrieve.
encryptedMessage
string
Optional. Arbitrary encrypted message from the session to retrieve.
Returns
Promise<string>
writeKeyBackup()
Write the internal key backup. For advanced use.
Parameters
encryptedKeyBackup
ArrayBuffer | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike>
Returns
Promise<void>
version
version:
string
The SDK version
Methods
addGroupMembers()
addGroupMembers(
groupId:string,newMembers:Recipients,newAdmins?:Recipients,silentKeyRenew?:boolean):Promise<void>
Add members to a group. Can only be done by a group administrator. Can also specify which of these group members should also be admins.
Parameters
groupId
string
id of the group
newMembers
id of members to add
newAdmins?
id of new members to also add as admins. This must be a subset of newMembers
silentKeyRenew?
boolean
Should renew the group key if needed, and the user is administrator of the group . Default to true.
Returns
Promise<void>
addMissingKeys()
addMissingKeys(
deviceId:string,retryOptions?: {nRetries:number;waitBetweenRetries:number; }):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 } = await sdk.eventBus.once('addMissingKeys-done')
Parameters
deviceId
string
retryOptions?
Optional.
nRetries
number
Optional. How many times to retry. Defaults to 3.
waitBetweenRetries
number
Optional. Time to wait between retries in milliseconds. Defaults to 30000ms = 30 seconds.
Returns
void
checkGroupSelfAddSecret()
checkGroupSelfAddSecret(
groupId:string):Promise<boolean>
Check if a self-add secret is set for a given group. Only accessible to group admins.
Parameters
groupId
string
Returns
Promise<boolean>
checkSigchainHash()
checkSigchainHash(
recipient:Recipients,sigchainHash:string,opts?: {position:number; }):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
recipient
sigchainHash
string
opts?
position
number
position of the sigchain transaction against which to check the hash. -1 for any transaction. Default to any transaction
Returns
Promise<{lastPosition: number;position: number; }>
lastPosition
lastPosition:
number
position
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>
convertGroupTMRTemporaryKey()
convertGroupTMRTemporaryKey(
groupId:string,temporaryKeyId:string,tmrJWT:string,rawOverEncryptionKey:string,opts?: {deleteOnConvert:boolean; }):Promise<void>
Convert group TMR temporary key to a group membership
Parameters
groupId
string
temporaryKeyId
string
The ID of the TMR temporary key to convert
tmrJWT
string
The JWT to use
rawOverEncryptionKey
string
TMR over-encryption key
opts?
Optional.
deleteOnConvert
boolean
Optional. Whether or not to delete the TMR temporary key. Default to false.
Returns
Promise<void>
convertTmrAccesses()
convertTmrAccesses(
tmrJWT:string,rawOverEncryptionKey:string,options?: {createdById:string;deleteOnConvert:boolean;sessionId:string;tmrAccessId:string; }):Promise<{errored:Record<string, {error: {code:string;id:string; };status:number; }>;succeeded:Record<string,string[]>; }>
Convert all TMR accesses addressed to a given auth factor and matching specified filters to classic message keys. All TMR accesses matching the specified filters must have been encrypted with the same rawOverEncryptionKey.
Parameters
tmrJWT
string
The JWT given at 2FA
rawOverEncryptionKey
string
The 2-man-rule key. This MUST be a cryptographically random string of 64 bytes B64 encoded.
options?
createdById
string
If specified, Seald ID of the user who created the TMR accesses to get
deleteOnConvert
boolean
Delete the 2-man-rule keys after conversion. Defaults to true.
sessionId
string
If specified, ID of the message for which to get TMR accesses
tmrAccessId
string
If specified, ID of the TMR accesses to get
Returns
Promise<{errored: Record<string, {error: {code: string;id: string; };status: number; }>;succeeded: Record<string, string[]>; }>
errored
errored:
Record<string, {error: {code:string;id:string; };status:number; }>
succeeded
succeeded:
Record<string,string[]>
createEncryptionSession()
createEncryptionSession(
recipients:RecipientsWithRights,opts?: {allowDownload:boolean;allowUnregisteredUsers:boolean;encryptForSelf:boolean;metadata:string;selfDestructDate:string;useCache:boolean; }):Promise<EncryptionSession>
Create an encryption session, with which you can then encrypt / decrypt multiple messages.
Parameters
recipients
Recipients for whom to encrypt.
opts?
Optional.
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.
allowUnregisteredUsers
boolean
Optional. Whether or not to allow non-seald, unregistered recipients. Defaults to false.
encryptForSelf
boolean
Optional. Whether or not to include the current account as recipient. Defaults to true
metadata
string
Optional. Arbitrary metadata string, not encrypted, for later reference. Max 1024 characters long.
selfDestructDate
string
Optional. Date at which the encrypted file should be automatically revoked. Format: 'YYYY-MM-DD'.
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<EncryptionSession>
createGroup()
createGroup(
args: {admins:Recipients;customGroupSymKey:string;expireAfter:number;groupName:string;members:Recipients;selfAddPassword:string;selfAddSecret:string; }):Promise<{groupName:string;id:string; }>
Create a group
Parameters
args
admins
Administrators of the group. Administrators must also be members. It must include yourself.
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.
expireAfter
number
Time after creation after which the keys should expire, in seconds. Default to 3 years, maximum 5 years.
groupName
string
Group name. Max 64 characters long.
members
Members of the group. It must include yourself.
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.
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; }>
groupName
groupName:
string
id
id:
string
createGroupTMRTemporaryKey()
createGroupTMRTemporaryKey(
groupId:string,args: {authFactor:TmrAuthFactor;forceGroupUpdate:boolean;isAdmin:boolean;rawOverEncryptionKey:string; }):Promise<GroupTMRTemporaryKey>
Create a group TMR temporary key.
Parameters
groupId
string
args
authFactor
TmrAuthFactor
forceGroupUpdate
boolean
Optional. Whether or not to force the update of the group before the operation
isAdmin
boolean
Admin status given when using TMR temporary key
rawOverEncryptionKey
string
TMR over encryption key. This MUST be the Base64 string encoding of a cryptographically random buffer of 64 bytes.
Returns
Promise<GroupTMRTemporaryKey>
createSubIdentity()
createSubIdentity(
opts?: {deviceName:string;expireAfter:number;nRetries:number;shouldReencrypt:boolean;waitBetweenRetries:number; }):Promise<{deviceId:string;identity:Buffer<ArrayBufferLike>; }>
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
addMissingKeyswith the newly createddeviceId, in order for the re-encryption to happen.
Parameters
opts?
Optional.
deviceName
string
Optional. Name of the new device. Max 36 characters long.
expireAfter
number
Time after creation after which the keys should expire, in seconds. Default to 3 years, maximum 5 years.
nRetries
number
Optional. How many times to retry re-encryption. Defaults to 3.
shouldReencrypt
boolean
Optional. Should trigger the re-encryption of missing message keys for the newly created device. Defaults to true.
waitBetweenRetries
number
Optional. Time to wait between retries in milliseconds. Defaults to 30000ms = 30 seconds.
Returns
Promise<{deviceId: string;identity: Buffer<ArrayBufferLike>; }>
deviceId
deviceId:
string
identity
identity:
Buffer<ArrayBufferLike>
decryptFile()
decryptFile<
T>(encryptedFile:T,opts?: {fileSize:number;lookupGroupKey:boolean;lookupProxyKey:boolean;progressCallback: (progress:number) =>void;useCache:boolean; }):Promise<{data:TextendsArrayBuffer|Uint8Array<ArrayBufferLike> |Buffer<ArrayBufferLike> ?Buffer<ArrayBufferLike> :T;filename:string;sessionId:string;size:number;type:FileType; }>
Decrypt an encrypted file.
Type Parameters
• T extends string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob | ReadableStream<any> | Readable | Buffer<ArrayBufferLike>
Parameters
encryptedFile
T
File to decrypt. Can be either a binary string, a Blob, a Buffer, or a stream. The function will return the decrypted file in same format.
opts?
Optional.
fileSize
number
Optional. Size of the file to decrypt. Needed when using progressCallback with a ReadableStream or NodeReadable as input type.
lookupGroupKey
boolean
should check for group rights
lookupProxyKey
boolean
should check for proxy rights
progressCallback
(progress: number) => void
Optional. Progress callback. The progress is given between 0 and 1.
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<{data: T extends ArrayBuffer | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike> ? Buffer<ArrayBufferLike> : T;filename: string;sessionId: string;size: number;type: FileType; }>
data
data:
TextendsArrayBuffer|Uint8Array<ArrayBufferLike> |Buffer<ArrayBufferLike> ?Buffer<ArrayBufferLike> :T
filename
filename:
string
sessionId
sessionId:
string
size
size:
number
type
type:
FileType
decryptMessage()
decryptMessage(
encryptedString:string,opts?: {lookupGroupKey:boolean;lookupProxyKey:boolean;useCache:boolean; }):Promise<string>
Decrypt a message.
Parameters
encryptedString
string
opts?
Optional.
lookupGroupKey
boolean
should check for group rights
lookupProxyKey
boolean
should check for proxy rights
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<string>
deleteGroup()
deleteGroup(
groupId:string):Promise<void>
Delete a group
Parameters
groupId
string
Returns
Promise<void>
deleteGroupTMRTemporaryKey()
deleteGroupTMRTemporaryKey(
groupId:string,temporaryKeyId:string):Promise<void>
Delete a groupTMRTemporaryKey
Parameters
groupId
string
temporaryKeyId
string
Key ID to delete
Returns
Promise<void>
dropDatabase()
dropDatabase():
Promise<void>
Drop local database, and delete locally saved backup key. It will also reset the current SDK instance. Call sdk.initialize() or sdk.initiateIdentity() afterward to continue with this sealdSDK instance.
Returns
Promise<void>
encryptFile()
encryptFile<
T>(clearFile:T,filename:string,recipients:RecipientsWithRights,opts?: {allowUnregisteredUsers:boolean;encryptForSelf:boolean;fileSize:number;metadata:string;progressCallback: (progress:number) =>void;selfDestructDate:string; }):Promise<TextendsArrayBuffer|Uint8Array<ArrayBufferLike> |Buffer<ArrayBufferLike> ?Buffer<ArrayBufferLike> :T>
Encrypt a file.
Type Parameters
• T extends string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob | ReadableStream<any> | Readable | Buffer<ArrayBufferLike>
Parameters
clearFile
T
File to encrypt. Can be either a binary string, a Blob, a Buffer, or a stream. The function will return the encrypted file in same format.
filename
string
Name of the file. Max 256 characters long.
recipients
Recipients for whom to encrypt
opts?
allowUnregisteredUsers
boolean
Optional. Whether or not to allow non-seald, unregistered recipients. Defaults to false.
encryptForSelf
boolean
Optional. Whether or not to include the current account as recipient. Defaults to true
fileSize
number
Optional. Size of the file to encrypt. Must be specified for ReadableStream and NodeReadable.
metadata
string
Optional. Arbitrary metadata string, not encrypted, for later reference. Takes filename as default value, use '' to override. Max 1024 characters long.
progressCallback
(progress: number) => void
Optional. Progress callback. The progress is given between 0 and 1.
selfDestructDate
string
Optional. Date at which the encrypted file should be automatically revoked. Format: 'YYYY-MM-DD'.
Returns
Promise<T extends ArrayBuffer | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike> ? Buffer<ArrayBufferLike> : T>
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'] }
)encryptMessage()
encryptMessage(
clearString:string,recipients:RecipientsWithRights,opts?: {allowUnregisteredUsers:boolean;encryptForSelf:boolean;metadata:string;raw:boolean;selfDestructDate:string; }):Promise<string>
Encrypt a message.
Parameters
clearString
string
recipients
opts?
Optional.
allowUnregisteredUsers
boolean
Optional. Whether or not to allow non-seald, unregistered recipients. Defaults to false.
encryptForSelf
boolean
Optional. Whether or not to include the current account as recipient. Defaults to true
metadata
string
Optional.Arbitrary metadata string, not encrypted, for later reference. Max 1024 characters long.
raw
boolean
Optional. Whether to include or not the sessionID in the encrypted string. If set to true, the encrypted string cannot be used to retrieve the encryption session. Defaults to false.
selfDestructDate
string
Optional. Date at which the encrypted file should be automatically revoked. Format: 'YYYY-MM-DD'.
Returns
Promise<string>
exportIdentity()
exportIdentity():
Promise<Buffer<ArrayBufferLike>>
Export the current identity, to handle it manually
Returns
Promise<Buffer<ArrayBufferLike>>
getCurrentAccountInfo()
getCurrentAccountInfo():
Promise<AccountInfo>
Get account info of current SDK instance.
Returns
Promise<AccountInfo>
getRSAKeyPromise()
getRSAKeyPromise(
size?:1024|2048|4096):Promise<string>
Function which create a promise that resolves to a newly generated b64 encoded RSA key.
Parameters
size?
1024 | 2048 | 4096
Returns
Promise<string>
getSigchainHash()
getSigchainHash(
recipient?:Recipients,opts?: {position:number; }):Promise<{hash:string;position:number;sealdId:string; }>
Get hash of a user last sigchain transaction. If no recipient is given, return the current user hash.
Parameters
recipient?
opts?
position
number
get the hash at the given position. -1 for last transaction. Default to last transaction
Returns
Promise<{hash: string;position: number;sealdId: string; }>
hash
hash:
string
position
position:
number
sealdId
sealdId:
string
heartbeat()
heartbeat():
Promise<void>
Send a heartbeat to the server.
Returns
Promise<void>
importIdentity()
importIdentity(
identity:ArrayBuffer|Uint8Array<ArrayBufferLike> |Buffer<ArrayBufferLike>):Promise<AccountInfo>
Import identity manually
Parameters
identity
ArrayBuffer | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike>
Returns
Promise<AccountInfo>
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: {displayName:string;expireAfter:number;signupJWT:string;userId:string;userLicenseToken:string; }):Promise<AccountInfo>
Create the account for the first time.
Parameters
args
displayName
string
Name to display this user under on the dashboard. Defaults to userId.
expireAfter
number
Time after creation after which the keys should expire, in seconds. Default to 3 years, maximum 5 years.
signupJWT
string
JWT to allow the current user to join your app's Seald Team. Must be generated by your server.
userId
string
Deprecated. 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.
userLicenseToken
string
Deprecated. The license token to allow the current user to join your app's Seald Team. Must be generated by your server.
Returns
Promise<AccountInfo>
listBackupKeys()
listBackupKeys(
acceptBackupKeys?:boolean):Promise<{created:Date;createdBy:string;id:string;name:string;publicKey:PublicKey; }[]>
List admin backup keys
Parameters
acceptBackupKeys?
boolean
Returns
Promise<{created: Date;createdBy: string;id: string;name: string;publicKey: PublicKey; }[]>
listGroupMembers()
listGroupMembers(
groupId:string):Promise<{displayName:string;id:string;isAdmin:boolean; }[]>
List members of a group
Parameters
groupId
string
Returns
Promise<{displayName: string;id: string;isAdmin: boolean; }[]>
listGroups()
listGroups(
args?: {all:boolean;mine:boolean;page:number; }):Promise<{lastPage:number;results: {bearduser: {displayName:string;id:string; };created:string;deviceId:string; }[]; }>
List all groups in team
Parameters
args?
Optional.
all
boolean
Optional. Return all pages at once.
mine
boolean
Optional. Show only groups of which the current user is a member
page
number
Optional.
Returns
Promise<{lastPage: number;results: {bearduser: {displayName: string;id: string; };created: string;deviceId: string; }[]; }>
lastPage
lastPage:
number
results
results: {
bearduser: {displayName:string;id:string; };created:string;deviceId:string; }[]
listGroupTMRTemporaryKeys()
listGroupTMRTemporaryKeys(
groupId:string,opts?: {all:boolean;page:number; }):Promise<{nbPage:number;results:GroupTMRTemporaryKey[]; }>
List Group TMR temporary keys for a given group.
Parameters
groupId
string
opts?
Optional.
all
boolean
Optional. Return all pages
page
number
Optional. Page to get
Returns
Promise<{nbPage: number;results: GroupTMRTemporaryKey[]; }>
nbPage
nbPage:
number
results
results:
GroupTMRTemporaryKey[]
preGenerateIdentityKeys()
preGenerateIdentityKeys(
n?:number):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.
Pre-generated identity keys will be used to accelerate all functions which need new identity keys: initiateIdentity, createSubIdentity, createGroup, renewGroupKey, renewKey.
Parameters
n?
number
Number of identity keys to pre-generate. Defaults to 1. Minimum 1. Maximum 10.
Returns
void
prepareRenew()
prepareRenew():
Promise<Buffer<ArrayBufferLike>>
PrepareRenew prepare a private key renewal, so it can be stored on SSKS without risk of loss during the actual renew
Returns
Promise<Buffer<ArrayBufferLike>>
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
pushJwt()
pushJwt(
jwt:string):Promise<{joinedTeam:boolean;userId:string; }>
Use a JWT on the current identity
Parameters
jwt
string
JWT to use. Must be generated by your server.
Returns
Promise<{joinedTeam: boolean;userId: string; }>
joinedTeam
joinedTeam:
boolean
userId?
optionaluserId:string
pushPreGeneratedIdentityKeyToPool()
pushPreGeneratedIdentityKeyToPool(
key:PreGeneratedIdentityKey):void
Add a previously retrieved identity key into the pool. Key is added at the end of the pool.
Parameters
key
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'.
The state 'no-team' is deprecated, and should never be returned.
Returns
Promise<"no-account" | "no-team" | "registered">
removeGroupMembers()
removeGroupMembers(
groupId:string,membersToRemove:Recipients,silentKeyRenew?:boolean):Promise<void>
Remove members from a group. Can only be done by a group administrator. You should call renewGroupKey after this.
Parameters
groupId
string
id of the group
membersToRemove
id of members to add
silentKeyRenew?
boolean
Should renew the group key if needed, and the user is administrator of the group . Default to true.
Returns
Promise<void>
renewGroupKey()
renewGroupKey(
groupId:string,options?: {customGroupSymKey:string;expireAfter:number;selfAddPassword:string; }):Promise<void>
Renew group private key. Should be called after removing members.
Parameters
groupId
string
id of the group
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.
expireAfter
number
Time after creation after which the keys should expire, in seconds. Default to 3 years, maximum 5 years.
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(
opts?: {expireAfter:number;preparedRenewal:Buffer<ArrayBufferLike>; }):Promise<void>
Renew the key of this Identity. In order to avoid any failure, we recommande to first use sdk.prepareRenew(), then save the prepared renewal on SSKS, and finally call sdk.renewKey({ preparedRenewal }).
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.
Parameters
opts?
expireAfter
number
Time after creation after which the keys should expire, in seconds. Default to 3 years, maximum 5 years.
preparedRenewal
Buffer<ArrayBufferLike>
Optional. A prepared renewal created using sdk.prepareRenew.
Returns
Promise<void>
retrieveEncryptionSession()
retrieveEncryptionSession<
T>(args: {encryptedFile:T;encryptedMessage:string;lookupGroupKey:boolean;lookupProxyKey:boolean;sessionId:string;useCache:boolean; }):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
• T extends string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob | ReadableStream<any> | Readable | Buffer<ArrayBufferLike>
Parameters
args
encryptedFile
T
Optional. Arbitrary encrypted file from the session to retrieve.
encryptedMessage
string
Optional. Arbitrary encrypted message from the session to retrieve.
lookupGroupKey
boolean
should check for group rights
lookupProxyKey
boolean
should check for proxy rights
sessionId
string
Optional. sessionId of the session to retrieve.
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<EncryptionSession>
retrieveEncryptionSessionByTmr()
retrieveEncryptionSessionByTmr(
sessionId:string,tmrJWT:string,rawOverEncryptionKey:string,options?: {createdById:string;tmrAccessId:string;tryIfMultiple:boolean;useCache:boolean; }):Promise<EncryptionSession>
Retrieve an EncryptionSession with Two Man Rule. If your Auth Factor has multiple TMR accesses for this message ID, you have to specify filters, or set tryIfMultiple to true.
Parameters
sessionId
string
tmrJWT
string
The JWT given at 2FA
rawOverEncryptionKey
string
The 2-man-rule key. This MUST be a cryptographically random string of 64 bytes B64 encoded.
options?
createdById
string
If specified, Seald ID of the user who created the TMR accesses to get
tmrAccessId
string
If specified, ID of the TMR Message Key to get
tryIfMultiple
boolean
If multiple TMR accesses are found matching the given criteria, try them all if true, throw an error if false.
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<EncryptionSession>
retrieveEncryptionSessionWithSymEncKey()
retrieveEncryptionSessionWithSymEncKey(
args: {sessionId:string;symEncKeyId:string;symEncKeyPassword:string;symEncKeyRawSecret:string;symEncKeyRawSymKey:string;useCache:boolean; }):Promise<EncryptionSession>
Retrieve an encryption session, with which you can then encrypt / decrypt multiple messages, with the sessionId and a SymEncKey.
You must pass either symEncKeyPassword, or both symEncKeyRawSecret and symEncKeyRawSymKey.
Parameters
args
sessionId
string
sessionId of the session to retrieve.
symEncKeyId
string
The symEncKeyId of the SymEncKey to use to retrieve the EncryptionSession.
symEncKeyPassword
string
The password used to create this SymEncKey.
symEncKeyRawSecret
string
The rawSecret used to create this SymEncKey.
symEncKeyRawSymKey
string
The rawSymKey used to create this SymEncKey.
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<EncryptionSession>
retrieveMultipleEncryptionSessions()
retrieveMultipleEncryptionSessions<
T>(toRetrieve: {encryptedFile:T;encryptedMessage:string;sessionId:string; }[],args?: {lookupGroupKey:boolean;lookupProxyKey:boolean;useCache:boolean; }):Promise<EncryptionSession[]>
Retrieve multiple encryption sessions.
The returned array of EncryptionSessions is in the same order as the input array.
Type Parameters
• T extends string | Blob | ReadableStream<any> | Readable | Buffer<ArrayBufferLike>
Parameters
toRetrieve
{encryptedFile: T;encryptedMessage: string;sessionId: string; }[]
args?
lookupGroupKey
boolean
should check for group rights
lookupProxyKey
boolean
should check for proxy rights
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<EncryptionSession[]>
searchGroupTMRTemporaryKeys()
searchGroupTMRTemporaryKeys(
tmrJWT:string,opts?: {all:boolean;groupId:string;page:number; }):Promise<{nbPage:number;results:GroupTMRTemporaryKey[]; }>
Search group TMR temporary keys that this tmrJWT could convert
Parameters
tmrJWT
string
The JWT to use
opts?
Optional. Search filters
all
boolean
Optional. Return all pages
groupId
string
Optional. Return only the TMR temporary keys giving access to this specific groupId
page
number
Optional. Page to get
Returns
Promise<{nbPage: number;results: GroupTMRTemporaryKey[]; }>
nbPage
nbPage:
number
results
results:
GroupTMRTemporaryKey[]
selfAddGroup()
selfAddGroup(
groupId:string,args: {groupSymKey:string;selfAddPassword:string;selfAddSecret:string; }):Promise<void>
Add self to a group with a self-add secret.
Parameters
groupId
string
args
Optional.
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.
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.
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>
selfAddToEncryptionSessionWithSymEncKey()
selfAddToEncryptionSessionWithSymEncKey(
args: {rights:UserRights;sessionId:string;symEncKeyId:string;symEncKeyPassword:string;symEncKeyRawSecret:string;symEncKeyRawSymKey:string;useCache:boolean; }):Promise<EncryptionSession>
Self-add to an encryption session, and return it, with the sessionId and a SymEncKey.
You can only call this if the SymEncKey has the forward right.
You must pass either symEncKeyPassword, or both symEncKeyRawSecret and symEncKeyRawSymKey.
Parameters
args
rights
Rights to assign to yourself on this session. Cannot contain rights that the SymEncKey does not have. Defaults to { read: true, forward: true, revoke: false }.
sessionId
string
sessionId of the session to retrieve.
symEncKeyId
string
The symEncKeyId of the SymEncKey to use to retrieve the EncryptionSession.
symEncKeyPassword
string
The password used to create this SymEncKey.
symEncKeyRawSecret
string
The rawSecret used to create this SymEncKey.
symEncKeyRawSymKey
string
The rawSymKey used to create this SymEncKey.
useCache
boolean
Whether or not to use the cache (if enabled globally). Default to true.
Returns
Promise<EncryptionSession>
setGroupAdmin()
setGroupAdmin(
groupId:string,groupMember:Recipients,statusToSet:boolean):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. This is deprecated. Use setGroupAdmins instead.
Parameters
groupId
string
groupMember
statusToSet
boolean
Returns
Promise<void>
Deprecated
setGroupAdmins()
setGroupAdmins(
groupId:string,groupMembers: {addToAdmins:Recipients;removeFromAdmins:Recipients; }):Promise<void>
Set admin status of group members. Can only be done by a group administrator.
Parameters
groupId
string
groupMembers
addToAdmins
removeFromAdmins
Returns
Promise<void>
setGroupSelfAddSecret()
setGroupSelfAddSecret(
groupId:string,args: {selfAddPassword:string;selfAddSecret:string; }):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
groupId
string
args
Optional.
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.
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:string):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
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:Recipients):Promise<void>
Update the local database for the specified recipients.
Parameters
r
Returns
Promise<void>
updateCurrentDevice()
updateCurrentDevice():
Promise<void>
Updates the locally known information about the current device.
You should never have to call this manually, except if you getting null in sealdAccountInfo.deviceExpires, which can happen if migrating from an older version of the SDK, or if the internal call to sdk.updateCurrentDevice failed when calling sdk.importIdentity.
Returns
Promise<void>