# 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

← @seald-io/sdk Interface: EncryptionSession →