feat(auth): add functions to help with removal of esri_auth cookie

[dbouwman]

In an upcoming release, the esri_auth clear-text cookie will be removed in favor of an encrypted esri_aopc cookie that client's can not read.

To get a token from the esri_aopc cookie, the app needs to call /oauth2/platformSelf, passing in the client_id and redirect_uri of the app for which they want an app-specific token to be issued.

This is exposed as platformSelf(clientId, redirectUri, portal?) -> {username: "jsmith", token: "aj8csja..."}

---

If the app has a token from another app (i.e. it is passed auth information via "postMessage") then the app can exchange that token for a token that is specific to the app.

For example - a Dashboard that is iframed into a Hub Site may get passed an ICredential via postMessage, but that credential contains a token for the Hub application.

To exchange that for a token that's specific to the Dashboard app, it can use the /oauth2/exchangeToken end-point, which is wrapped in to REST-JS as exchangeToken(currentToken, clientId, portal) -> {token: "ashda898ds..."}

---

Finally, to streamline checking if the current user has access to the app, and if the app should present a "Viewer" UX, there is the /oauth2/validateAppAccess end point, which is wrapped as validateAppAccess(token, clientId) -> {valid: true, viewOnlyUserTypeApp: false}
This is also exposed in the UserSession object as session.validateAppAccess(clientId) -> {valid: true, viewOnlyUserTypeApp:false}

These functions are all specifically for Esri "Platform" applications hosted on *.arcgis.com or within an Enterprise Portal. Other apps will receive errors calling these functions.

[codecov]

Codecov Report

Merging #774 (613e00a) into master (9dfebbb) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master      #774   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          117       119    +2     
  Lines         1882      1905   +23     
  Branches       321       324    +3     
=========================================
+ Hits          1882      1905   +23     

Impacted Files	Coverage Δ
packages/arcgis-rest-auth/src/UserSession.ts	100.00% <100.00%> (ø)
packages/arcgis-rest-auth/src/app-tokens.ts	100.00% <100.00%> (ø)
...ckages/arcgis-rest-auth/src/validate-app-access.ts	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9dfebbb...065cb1e. Read the comment docs.

[tomwayson]

werks for me