Class: Invite
invite.Invite
The Invite
class encapsules most of the logic and information necessary to
perform a key exchange between an Org and
Account before adding the Account as a
member. A secret HMAC key is used to sign and verify the public keys of both
invitee and organization. This key is derived from a
secret, which needs to be communicated between the
organization owner and invitee directly.
The invite flow generally works as follows:
// ORG OWNER
const invite = new Invite("bob@example.com", "add_member");
// Generates random secret and signs organization details
await invite.intialize(../org, orgOwnerAccount);
console.log("invite secret: ", invite.secret);
// => Invite object is send to server, which sends an email to the invitee
// INVITEE
// => Invitee fetches `invite` object from server, asks org owner for `secret` (in person)
// Verifies organization info and signs own public key
const success = await invite.accept(../inviteeAccount, secret);
if (!success) {
throw "Verification failed! Incorrect secret?";
}
// => Sends updated invite object to server
// ORG OWNER
// => Fetches updated invite object
// Verify invitee details.
if (!(await invite.verifyInvitee())) {
throw "Failed to verify invitee details!";
}
// DONE!
await org.addOrUpdateMember(../invite.invitee);
Hierarchy
-
↳
Invite
Constructors
constructor
• new Invite(email?
, purpose?
)
Parameters
Name | Type | Default value |
---|---|---|
email |
string |
"" |
purpose |
InvitePurpose |
"join_org" |
Overrides
Defined in
Properties
_key
• Protected
Optional
_key: Uint8Array
The key used for encryption. Sub classes must set this property in the unlock method.
Inherited from
Defined in
_propertySerializationOptions
• _propertySerializationOptions:
SerializationOptions
[]
Inherited from
SimpleContainer._propertySerializationOptions
Defined in
_secret
• Private
Optional
_secret: string
= ""
Defined in
_signingKey
• Private
Optional
_signingKey: null
| Uint8Array
= null
Defined in
created
• created: Date
Time of creation
Defined in
• email: string
= ""
encryptedData
• Optional
encryptedData: Uint8Array
Encrypted data
Inherited from
Defined in
encryptionParams
• encryptionParams: AESEncryptionParams
Parameters used for encryption of content data
Inherited from
SimpleContainer.encryptionParams
Defined in
expires
• expires: Date
Expiration time used to limit invite procedure to a certain time window. This property is also stored in encryptedData along with the invite secret to prevent tempering.
Defined in
id
• id: string
= ""
Unique identfier
Defined in
invitedBy
• Optional
invitedBy: Object
= undefined
Info about who created the invite.
Type declaration
Name | Type |
---|---|
accountId |
string |
email |
string |
name |
string |
Defined in
invitee
• invitee: InviteeInfo
Invitee info, including HMAC signature used for verification Set when the invitee successfully accepts the invite
Defined in
org
• org: OrgInfo
Organization info, including HMAC signature used for verification. Set during initialization
Defined in
purpose
• purpose: InvitePurpose
=
"join_org"
signingKeyParams
• signingKeyParams: PBKDF2Params
Key derivation paramaters used for deriving the HMAC signing key from secret.
Defined in
signingParams
• signingParams: HMACParams
Parameters used for signing organization and initee details.
Defined in
Accessors
accepted
• get
accepted(): boolean
Whether this invite has been accepted by the invitee
Returns
boolean
Defined in
expired
• get
expired(): boolean
Whether this invite has expired
Returns
boolean
Defined in
kind
• get
kind(): string
A string representing the objects "type", useful for segmenting storage, among other things. Defaults to the lowercase class name, but can be overwritten by subclasses
Returns
string
Inherited from
SimpleContainer.kind
Defined in
secret
• get
secret(): undefined
| string
Random secret used for deriving the HMAC key that is used to sign and verify organization and invitee details. It is encrypted at rest with an AES key only available to organization admins. The invitee does not have access to this property directly but needs to request it from the organization owner directly.
secret
IMPORTANT: This property is considered secret and should
never stored or transmitted in plain text
Returns
undefined
| string
Defined in
• set
secret(s
): void
Random secret used for deriving the HMAC key that is used to sign and verify organization and invitee details. It is encrypted at rest with an AES key only available to organization admins. The invitee does not have access to this property directly but needs to request it from the organization owner directly.
secret
IMPORTANT: This property is considered secret and should
never stored or transmitted in plain text
Parameters
Name | Type |
---|---|
s |
undefined | string |
Returns
void
Defined in
Methods
_fromRaw
▸ Protected
_fromRaw(raw
): void
Restore values from a raw object. The default implementation simply copies over all iterable properties from the base object. Overwrite this method for properties that require special treatment
Parameters
Name | Type |
---|---|
raw |
any |
Returns
void
Inherited from
Defined in
_getSigningKey
▸ Private
_getSigningKey(): Promise
<Uint8Array
>
Returns
Promise
<Uint8Array
>
Defined in
_sign
▸ Private
_sign(val
): Promise
<Uint8Array
>
Parameters
Name | Type |
---|---|
val |
Uint8Array |
Returns
Promise
<Uint8Array
>
Defined in
_toRaw
▸ Protected
_toRaw(version
): any
Transform this object into a raw javascript object used for serialization. The default implementation simply copies all iterable properties not included in the [[exlude]] array and calls toRaw on any properties that are themselfes instances of Serializable. This method should be overwritten by subclasses if certain properties require special treatment.
Parameters
Name | Type |
---|---|
version |
undefined | string |
Returns
any
Inherited from
Defined in
_verify
▸ Private
_verify(sig
, val
): Promise
<boolean
>
Parameters
Name | Type |
---|---|
sig |
Uint8Array |
val |
Uint8Array |
Returns
Promise
<boolean
>
Defined in
accept
▸ accept(account
, secret
): Promise
<boolean
>
Accepts the invite by verifying the organization details and, if successful, signing and storing the invitees own information. Throws if verification is unsuccessful.
Parameters
Name | Type |
---|---|
account |
Account |
secret |
string |
Returns
Promise
<boolean
>
Defined in
clone
▸ clone(): Invite
Creates a deep clone of the object
Returns
Inherited from
Defined in
fromBytes
▸ fromBytes(bytes
): Invite
Deserializes the object from a byte array
Parameters
Name | Type |
---|---|
bytes |
Uint8Array |
Returns
Inherited from
Defined in
fromJSON
▸ fromJSON(json
): Invite
Deserializes the object from a JSON string
Parameters
Name | Type |
---|---|
json |
string |
Returns
Inherited from
Defined in
fromRaw
▸ fromRaw(raw
): Invite
Restores propertiers from a raw object of the same form generated by
toRaw. The base implementation blindly copies over
values from the raw object via Object.assign
so subclasses should explictly
process any propertyies that need special treatment.
Also takes are of validation and "upgrading" in case the raw object has an old version. Use the protected _fromRaw method to implement subclass-specific behavior.
Parameters
Name | Type |
---|---|
raw |
any |
Returns
Inherited from
Defined in
getData
▸ getData(): Promise
<Uint8Array
>
Decrypts and extracts the plain text data from the container. This will usually require unlocking the container first.
Returns
Promise
<Uint8Array
>
Inherited from
Defined in
initialize
▸ initialize(org
, invitor
, duration?
): Promise
<void
>
Initializes the invite by generating a random secret and id and signing and storing the organization details.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
org |
Org |
undefined |
The organization this invite is for |
invitor |
Account |
undefined |
Account creating the invite |
duration |
number |
12 |
Number of hours until this invite expires |
Returns
Promise
<void
>
Defined in
lock
▸ lock(): void
Locks the container, removing the possibility to extract the plain text data via getData until the container is unlocked again. Subclasses extending this class must take care to delete any keys or other sensitive data that may have been stored temporarily after unlocking the container.
Returns
void
Overrides
Defined in
setData
▸ setData(data
): Promise
<void
>
Encrypts the provided data
and stores it in the container
Parameters
Name | Type |
---|---|
data |
Uint8Array |
Returns
Promise
<void
>
Inherited from
Defined in
toBytes
▸ toBytes(): Uint8Array
Returns a serialization of the object in form of a byte array
Returns
Uint8Array
Inherited from
Defined in
toJSON
▸ toJSON(): string
Returns a JSON serialization of the object
Returns
string
Inherited from
Defined in
toRaw
▸ toRaw(version?
): any
Creates a raw javascript object representation of the class, which can be used for storage or data transmission. Also handles "downgrading" to previous versions. Use _toRaw for subclass-specific behavior.
Parameters
Name | Type |
---|---|
version? |
string |
Returns
any
Inherited from
Defined in
unlock
▸ unlock(key
): Promise
<void
>
"Unlocks" the invite with the dedicated key (owned by the respective Org). This grants access to the secret property and verfies that expires has not been tempered with.
Parameters
Name | Type |
---|---|
key |
Uint8Array |
Returns
Promise
<void
>
Overrides
Defined in
validate
▸ validate(): boolean
This is called during deserialization and should verify that all properties have been populated with values of the correct type. Subclasses should implement this method based on their class structure.
Returns
boolean
Inherited from
Defined in
verifyInvitee
▸ verifyInvitee(): Promise
<boolean
>
Verifies the invitee information.
Returns
Promise
<boolean
>
Defined in
verifyOrg
▸ verifyOrg(): Promise
<boolean
>
Verifies the organization information.
Returns
Promise
<boolean
>