a share / role change. There are 3 different permutations * that have slightly different meanings: * * * Only `principal` is set: The target for the share is some principal (user or group) and the * appropriate interaction checks should be performed for the target * * Only `email` is set: The target is an email invitation * * Both `principal` and `email` are set: If the email matches the email of the principal * profile, then interaction checks can be bypassed as the client has successfully * looked up the user by email * * A `role` can optionally be present with the target, indicating a role change to apply to the * target * * @param {Principal} [principal] The principal profile * @param {String} [email] The email address * @param {String} [role] The role change to apply, if applicable */