CHARP JavaScript API - pupitetris/charp GitHub Wiki

The most common usage scenario for CHARP is with a web browser as a client. On the other hand, CHARP can be used with any language as long as you are able to do HTTP connections, encode and decode JSON data structures and optionally perform the SHA256 algorithm if you are using challenge authentication.

Table of Contents Dependencies Performing requests Initialization APP.main Constructor Credential management

JavaScript was the first target client language to implement the CHARP protocol, with the help of a few external libraries, which are already included with CHARP, residing in site/htdocs/script:

• jsSHA http://jssha.sourceforge.net/ - found as lib/sha256.min.js, for the challenge signature.
• webtoolkit md5 http://www.webtoolkit.info/javascript-md5.html - found as lib/webtoolkit.md5.min.js, used to obscure passwords residing in memory and local storage. This is only mandatory if you plan to store passwords in your server using MD5; you may use any hashing algorithm you may want, or keep them in plain text; your choice.
• JSON-js http://github.com/douglascrockford/JSON-js - found as lib/json2.min.js, used to serialize request parameters and deserialize reply results for browsers that lack native JSON functionality.
• jQuery http://jquery.com/ - found as lib/jquery.min.js, used to facilitate XHT requests and JSON results. Note: we regard dropping the jQuery dependency as desirable, to reduce the footprint of JavaScript CHARP.
• jQuery UI http://jqueryui.com/ - found as lib/jquery.ui.min.js, used for error reporting messages for the user. The default error handler will eventually be parametrizable to set the jQuery UI dependency as optional.
• app.js - found as app.js, it's our collection of utility functions. This is what actually depends on jQuery and jQuery UI. Note: dependency of CHARP.js on this library will eventually be dropped too.

CHARP requests are performed asynchronously; that means that you register the resource and parameters that you wish to execute on the server, along with callback functions that will be ran as soon as your request is completed. Request registration returns immediately and your program continues to run normally. Eventually your request will give a result and one of your callbacks will be called, depending if the result was an error or if it gave successful data. Lots of things happen in the background for this call to be as transparent as possible.

For your webpage or application to run CHARP requests, you need to include the CHARP library and its dependencies. You can use the site/htdocs/app.html file as a guide:

 <link rel="stylesheet" type="text/css" href="style/theme/jquery.ui-theme.css" />
 <script type="text/javascript" src="script/lib/jquery.min.js"></script>
 <script type="text/javascript" src="script/lib/jquery.ui.min.js"></script>
 <script type="text/javascript" src="script/lib/jquery.validate.min.js"></script>
 <script type="text/javascript" src="script/lib/sha256.min.js"></script>
 <script type="text/javascript" src="script/lib/webtoolkit.md5.min.js"></script>
 <script type="text/javascript" src="script/CHARP.js"></script>
 <script type="text/javascript" src="script/app.js"></script>

Now we need to define a CHARP object to make our transactions. Although you may define as many as you want, you only need one CHARP object instance for the whole of your application, since a CHARP object can take care of multiple transactions, both concurrently and over time, so it's not uncommon to define your CHARP instance as a global.

For your convenience, app.js runs an event handler for when the DOM document loads where it runs APP.main if it has been defined by you. You may consider the APP "namespace" as a place where you can store global functions and object for your applications, so the following main function is not uncommon:

 <script type="text/javascript">
  APP.main = function () {
    APP.charp = new CHARP ().init ();
  };
 </script>

As you can observe, the CHARP object is not simply constructed with the new operator, but a method init is called right after the object has been returned by the constructor.

All of our objects have to be constructed this way, by calling new on the JavaScript class function and then calling init on the newly created object. init functions always return the object, so the assigned variable can catch the object's reference as usual.

This method follows the Objective-C philosophy, where the constructor is only used for allocation, and init is used to actually initialize the object's state. In JavaScript this allows us to define the class function as an empty function and let all of the initialization of the object to take place within its init function which resides inside its class prototype alongside with the other methods.

The init method can optionally receive two arguments:

 CHARP.init ([''login'', [''passwd_hash'']])

This is useful if you decide to delay the initialization of your CHARP object until the user provides its username (also called login) and password.

The second argument is called passwd_hash to denote that it should be hashed just as passwords are being hashed on the server, probably using MD5, SHA1 or some other similar algorithm. CHARP is agnostic regarding this as it uses the provided string as-is to sign the challenge, so it doesn't care about the format of its contents and it doesn't use it in any altered form. The only thing is that the same password must be represented in the same way for this argument as it is represented in the account table in the project's database.

CHARP can optionally store the given login and password credentials in the user's HTML5 local storage so they can be recovered at a later time to avoid repeatedly asking for them. For these purposes, we provide the following methods:

 CHARP.credentialsSet (''login'', ''passwd_hash'')

 CHARP.credentialsSave ()

 CHARP.credentialsLoad ()

 CHARP.credentialsDelete ()

credentialsSet simply stores the given login and password hash into the object's internal state, but not on local storage. This should be called at least once in the application's lifespan to allow authentication to take place (unless you are implementing a site with nothing but anon remote procedures). This function is called by the init method as well. Trivially, if you call this method with undefined or empty strings, the credentials currently held will be overwritten with empty information (in case a log out is performed by the user, for example).

credentialsSave will take the internal state's login and password hash and put them into local storage for later retrieval. This will allow the credentials to be later recovered when the user subsequently visits the application's page, avoiding repetitive credential requests to the user.

credentialsLoad loads the saved login and password hash and stores them in the object's internal state. The login is returned to let the application check if credentials were actually present in the user's local storage and act accordingly.

credentialsDelete removes the credentials from local storage.

Once the credentials are set in the object's internal state, we are ready to send requests to the server.