[SDK-2306] Add login and signup hooks

[stevehobbsdev]

Changes

This PR adds new functionality to add two async hooks that the developer can use to hook into the form submission process on login and signUp. The developer can handle these events then call a callback function to signal that their own processing has been completed before continuing. Or, they can throw an error which can be displayed on the Lock form that then cancels the login or signup process.

Available hooks

• loggingIn - called when the user presses the login button; after validating the login form, but before calling the login endpoint
• signingUp - called when the user presses the button on the sign-up page; after validating the signup form, but before calling the sign up endpoint

Both hooks accept two arguments:

• context - this argument is currently always null but serves as a future-proofing mechanism to support providing additional data without us requiring breaking changes to the library
• cb - a callback function to call when the hook is finished. Execution of the login or signup process is blocked until this is called

API

new Auth0Lock('client ID', 'domain', {
  hooks: {
    loggingIn: function(context, cb) {
      console.log('Hello from the login hook!');
      cb();
    },
    signingUp: function(context, cb) {
      console.log('Hello from the sign-up hook!');
      cb();
    }
});

Error handling

The developer can throw an error to block the login or sign-up process. The developer can either specify a specific object and show the error on the page, or throw a generic error which causes Lock to show a fallback error:

new Auth0Lock('client ID', 'domain', {
  hooks: {
    loggingIn: function(context, cb) {
      // Throw an object with code: `hook_error` to display this on the Login screen
      throw { code: 'hook_error', description: 'There was an error in the login hook!' };

      // Throw something generic to show a fallback error message
      throw "Some error happened";
    },
});

Testing

Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and/or integration testing, tests should be added for new functionality and existing tests should complete without errors.

• This change adds unit test coverage
• This change adds integration test coverage
• This change has been tested on the latest version of the platform/language

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors
• All code quality tools/guidelines have been run/followed
• All relevant assets have been compiled
• All active GitHub checks have passed

[stevehobbsdev]

Lock already had an internal "hooks" mechanism that wasn't available to be used outside of the library. This change piggy-backs onto that and defers to a publicly-registered hook if one is available. Otherwise, it runs the private internal hook if available.

[stevehobbsdev]

Runs args[1] since the inputs to a public hook are the context and the callback function, in that order.

[adamjmcgrath]

hooks: {
    loggingIn: function(context, done) {
        throw { code: 'hook_error', description: 'can you put <i>HTML</i> in here?' };
    },

I wonder if this is a risk, given that a hook_error is more likely to have reflected user input than a rule_error

[stevehobbsdev]

It's a good point. Currently you could put HTML in there, but for that to be reflected from user input the developer would have to specifically get it from the HTML within their hook, we don't give you those values in the context.

However, in the future there may be a case for making those available where HTML could inadvertently be written out, so we could clamp that down now and encode HTML when the error is output. Let me add that to the PR.

[stevehobbsdev]

I can see a use case for developer's wanting to display links in here. Seeing as the developer has to go out of their way to reflect user input in this field, let's cover it with guidance and make people aware that this will display HTML if you give it HTML.

Covered in ba9950a