edsu-grant.js

CDN Linkhttps://edsu-cdn.org/libs/edsu-grant/0.1/edsu-grant.js
CDN Minified Linkhttps://edsu-cdn.org/libs/edsu-grant/0.1/edsu-grant.min.js

This libary is an implementation of the inter-tab protocol for a webapp to request a permissions grant from an Edsu user.

It's comprised of two functions: edsuUsernameElement() and edsuGrantRequest().

edsuUsernameElement(cb)

This creates a widget for entering an Edsu username. Its goal is to help provide a consisent, recognizable UX across all Edsu apps for this function. Having said that, it's only purpose is to get the user's username, so if you would like to get that information any other way, you can safely ignore this function, or use the HTML version instead.

The single parameter is cb (short for callback), which is the function called when the user either presses enter or the → button. The callback will receive one argument: an object with the property username, which contains the string that the user entered. It is trim()ed, but not validated or altered in any other way.

edsuGrantRequest(username, request, cbs)

Calling this function will open a tab at a URL controlled by the Edsu user username. This tab presents your request and the opportunity to grant or refuse it.

The second argument should be an object with the following properties:

capabilitiesOwner Optional. This is an object that will be run through Edsu.encodeEson() to produce what must be a valid capabilities block. These are the capabilities which you are requesting for your app. To learn more about capabilities blocks, refer to that section of the specification.
capabilitiesVisitor Optional. This is as capabilitiesOwner except it's the visitor capabilities which you are requesting.
explanation Optional. This is where you have a chance to explain the reasons behind the permissions that you've requested. The user will decide whether the names in the request reasonably map to the functionality that your app provides - use this to make that decision more straightforward by providing clarity. The value of this parameter is a string in CommonMark format with no extensions, and with HTML tags are stripped out before conversion.
label Optional. The user can label each grant - this is useful if later they want to rescind it, for example. This parameter is a plain-text unicode string which will presented as your suggestion for this label, but may be overridden by the user.
durationSeconds Optional. The user can restrict a grant to expire after a certain amount of time. In the same way as label this provides an overridable suggestion for how long this grant will last from now. Omitting this parameter is synonymous with not suggesting any expiration.
once Optional. In a similar manner to durationSeconds, the user can restrict a grant to self-delete after a single use. Likewise, this is an overridable suggestion.

The third argument (for cbs, short for callbacks) is an object containing two parameters: err and granted.

err

The err callback receives a single argument, an object with two properties:

err This is a code representing the type of error. It will be one of the following symbols:
  • EdsuGrantError.refused - The user pressed the "refuse" button to deny your request
  • EdsuGrantError.refusedByHost - The user's account's host refused your request without ever presenting it to the user. Typically this is because it asked for resources that it never allows (e.g. for security reasons).
  • EdsuGrantError.invalidInput - The request sent was not formatted correctly
  • EdsuGrantError.comms - Communications with the granting tab has failed for some reason.
  • EdsuGrantError.edsuComms - Communications between the granting tab and the user's Edsu host failed for some reason.
debug A message meant for you the developer, adding additional information to the error code which might assist you in debugging.

granted

The granted callback receives a single argument, an object with up to five properties:

ok This will always contain the boolean value true.
tokenOwner Optional. This will be a string containing the token used to obtain the owner capabilities requested.
tokenVisitor Optional. Same as tokenOwner, for the visitor capabilities requested.
expires Optional. When the token(s) will expire, an integer representing a number seconds since the UNIX epoch. This may not be related to the duration that you suggested.
once Optional. If the user has selected that the grant expire after one use, this property will contain the boolean value true. As with expires, this may not be what you suggested.