From 53b5e30dc2111339b2a4cb4bbd939b21c8a756d6 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Wed, 15 Feb 2017 10:50:53 -0700 Subject: [PATCH] update README --- README.md | 76 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 44 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 17dcd44..991cf0f 100644 --- a/README.md +++ b/README.md @@ -147,21 +147,29 @@ Stable API -* `OAUTH3.utils.clientUri(window.location);` produces the default `client_uri` of your app (also used as `client_id`) -* `OAUTH3.discover(providerUri, { client_id: clientUri });` Promises the config file for the provider and caches it in memory. -* `OAUTH3.implicitGrant(providerUri, { client_id: clientUri })` returns a `session` with `session.token.sub` as the secure ppid. - * `debug: true` will cause the windows to not refresh automatically - * `windowType: 'popup'` will use a popup window to ask user for new permissions, if any - * `windowType: 'background'` will automatically log the user in (if all permissions have been accepted) -* `OAUTH3.request({ method: 'GET', url: '', session: '', data: '' })` make an authenticated request to a resource -* `OAUTH3.logout(providerUri, { client_id: clientUri, session: session })` opens a popup to confirm logout from the provider - * Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this -* `OAUTH3.urls.discover(providerUri, { client_id: clientUri })` generates a correctly parameterized url -* `OAUTH3.urls.implicitGrant(directives, { client_id: clientUri })` generates a correctly parameterized url -* `OAUTH3.urls.refreshToken(directives, opts)` generates a correctly parameterized url - * `opts.client_id = clientUri` - * `opts.access_token = ` - * `opts.refresh_token = ` +``` +OAUTH3.utils.clientUri(window.location); // produces the default `client_uri` of your app (also used as `client_id`) + +OAUTH3.discover(providerUri, { client_id: clientUri }); // Promises the config file for the provider and caches it in memory. + +OAUTH3.implicitGrant(providerUri, { client_id: clientUri }) // returns a `session` with `session.token.sub` as the secure ppid. + // debug: true - will cause the windows to not refresh automatically + // windowType: 'popup' - will use a popup window to ask user for new permissions, if any + // windowType: 'background' - will automatically log the user in (if all permissions have been accepted) + +OAUTH3.request({ method: 'GET', url: '', session: '', data: '' }) // make an authenticated request to a resource + +OAUTH3.logout(providerUri, { client_id: clientUri, session: session }) // opens a popup to confirm logout from the provider + // Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this + +OAUTH3.urls + .discover(providerUri, { client_id: clientUri }) // generates a correctly parameterized url + .implicitGrant(directives, { client_id: clientUri }) // generates a correctly parameterized url + .refreshToken(directives, opts) // generates a correctly parameterized url + // opts.client_id = clientUri + // opts.access_token = + // opts.refresh_token = +``` @@ -178,16 +186,18 @@ DO NOT rely on them. Many of them WILL change (we just wanted to publish with th Public utilities for browser and node.js: -* `OAUTH3.jwt` - * `OAUTH3.jwt.decode(''); // { iat, iss, aud, sub, exp, ttl } +``` +OAUTH3.jwt + .decode(''); // { iat, iss, aud, sub, exp, ttl } -* `OAUTH3.utils` - * `OAUTH3.utils.query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true` - * `OAUTH3.utils.scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts'` - * `OAUTH3.utils.uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect'` - * `OAUTH3.utils.url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect'` - * `OAUTH3.utils.url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api'` - * `OAUTH3.utils.atob(''); // '' (typically json ascii)` +OAUTH3.utils + .query.stringify({ access_token: '...', debug: true }); // access_token=...&debug=true + .scope.stringify([ 'profile', 'contacts' ]); // 'profile,contacts' + .uri.normalize('https://oauth3.org/connect/'); // 'oauth3.org/connect' + .url.normalize('oauth3.org/connect/'); // 'https://oauth3.org/connect' + .url.resolve('oauth3.org/connect/', '/api/'); // 'https://oauth3.org/connect/api' + .atob(''); // '' (typically json ascii) +``` Internal API ------------ @@ -195,16 +205,18 @@ Internal API This APIs will absolutely change before they are made public (at the very least the leading `_` will be removed) -* `OAUTH3.jwt` - * `OAUTH3.jwt.freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl) +``` +OAUTH3.jwt + .freshness(tokenMeta, staletimeSeconds, _now); // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl) -* `OAUTH3.utils` - * `OAUTH3.utils.url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect'` - * `OAUTH3.utils._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob` - * `OAUTH3.utils.randomState(); // a 128-bit crypto-random string` - * `OAUTH3.utils._insecureRandomState(); // a fallback for randomState() in old browsers` +OAUTH3.utils + .url._normalizePath('oauth3.org/connect/'); // 'oauth3.org/connect' + ._urlSafeBase64ToBase64(b64); // makes base64 safe for window.atob + .randomState(); // a 128-bit crypto-random string + ._insecureRandomState(); // a fallback for randomState() in old browsers -* `OAUTH3._browser` a collection of things a browser needs to perform requests +OAUTH3._browser // a collection of things a browser needs to perform requests +``` Roadmap -------