kylefang/stacks.js
1
0
Fork 0
mirror of https://github.com/alexgo-io/stacks.js.git synced 2026-05-29 00:41:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

updated docs

Browse Source
This commit is contained in:
Larry Salibra
2018-09-10 18:59:21 +08:00
parent ce46802464
commit 08fa5a6a8e
9 changed files with 3113 additions and 1161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
dist/blockstack.js vendored
View File

@@ -12,17 +12,54 @@ var _authConstants = require('./authConstants');
function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
// modeled after what we have in Android
// https://github.com/blockstack/blockstack-android/blob/d70864acdc12f50bd90fb276853c523845e04e22/blockstack-sdk/src/main/java/org/blockstack/android/sdk/BlockstackConfig.kt#L14
/**
* Configuration data for the current app.
*
* On browser platforms, creating an instance of this
* class without any arguments will use
* `window.location.origin` as the app domain.
* On non-browser platforms, you need to
* specify an app domain as the first argument.
* @type {AppConfig}
*/
var AppConfig = exports.AppConfig = function () {
// this needs to be on appDomain so only accept paths
/**
* @param {string} appDomain - the app domain
* @param {Array<string>} scopes - permissions this app is requesting
* @param {string} redirectPath - path on app domain to redirect users to after authentication
* @param {string} manifestPath - path relative to app domain of app's manifest file
* @param {string} coreNode - override the default or user selected core node
* @param {string} authenticatorURL - the web-based fall back authenticator
*/
/**
* The URL of Blockstack core node to use for this app. If this is
* `null`, the core node specified by the user or default core node
* will be used.
* @type {string}
*/
/**
* Path on app domain to redirect users to after authentication. The
* authentication response token will be postpended in a query.
* @type {string}
*/
/**
* Blockstack apps are uniquely identified by their app domain.
* @type {string}
*/
function AppConfig() {
var appDomain = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : window.location.origin;
var scopes = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : _authConstants.DEFAULT_SCOPE.slice();
var redirectPath = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : '/';
var redirectPath = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : '';
var manifestPath = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '/manifest.json';
var coreNode = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : null;
var authenticatorURL = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : _authConstants.DEFAULT_BLOCKSTACK_HOST;
_classCallCheck(this, AppConfig);
@@ -36,12 +73,38 @@ var AppConfig = exports.AppConfig = function () {
} else {
this.coreNode = coreNode;
}
this.authenticatorURL = authenticatorURL;
}
// if null, use node passed by auth token v1.3 or otherwise core.blockstack.org
/**
* The location to which the authenticator should
* redirect the user.
* @returns {string} - URI
*/
// this needs to be on appDomain so only accept paths
/**
* The URL of a web-based Blockstack Authenticator to use in the event
* the user doesn't have Blockstack installed on their machine. If this
* is not specified, the current default in this library will be used.
* @type {string}
*/
/**
* Path relative to app domain of app's manifest file.
*
* This file needs to have CORS headers set so that it can be fetched
* from any origin. Typically this means return the header `Access-Control-Allow-Origin: *`.
* @type {string}
*/
/**
* An array of string representing permissions requested by the app.
* @type {[Array<string>}
*/
_createClass(AppConfig, [{
@@ -49,6 +112,12 @@ var AppConfig = exports.AppConfig = function () {
value: function redirectURI() {
return '' + this.appDomain + this.redirectPath;
}
/**
* The location of the app's manifest file.
* @returns {string} - URI
*/
}, {
key: 'manifestURI',
value: function manifestURI() {
@@ -104,17 +173,21 @@ var DEFAULT_PROFILE = {
* The user is redirected to the `blockstackIDHost` if the `blockstack:`
* protocol handler is not detected. Please note that the protocol handler detection
* does not work on all browsers.
* @param {UserSession} caller - the instance calling this method
* @param {String} authRequest - the authentication request generated by `makeAuthRequest`
* @param {String} blockstackIDHost - the URL to redirect the user to if the blockstack
* protocol handler is not detected
* @return {void}
* @private
*/
};function redirectToSignInWithAuthRequestImpl(authRequest) {
var blockstackIDHost = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : _authConstants.DEFAULT_BLOCKSTACK_HOST;
};function redirectToSignInWithAuthRequestImpl(caller, authRequest) {
var protocolURI = _utils.BLOCKSTACK_HANDLER + ':' + authRequest;
var httpsURI = blockstackIDHost + '?authRequest=' + authRequest;
var httpsURI = _authConstants.DEFAULT_BLOCKSTACK_HOST + '?authRequest=' + authRequest;
if (caller.session && caller.session.appConfig && caller.session.appConfig.authenticatorURL) {
httpsURI = caller.session.appConfig.authenticatorURL + '?authRequest=' + authRequest;
}
// If they're on a mobile OS, always redirect them to HTTPS site
if (/Android|webOS|iPhone|iPad|iPod|Opera Mini/i.test(navigator.userAgent)) {
@@ -161,7 +234,7 @@ var DEFAULT_PROFILE = {
function redirectToSignInImpl(caller) {
var transitKey = caller.generateAndStoreTransitKey();
var authRequest = caller.makeAuthRequest(transitKey);
redirectToSignInWithAuthRequestImpl(authRequest);
redirectToSignInWithAuthRequestImpl(caller, authRequest);
}
/**
@@ -1192,10 +1265,12 @@ var SessionData = exports.SessionData = function () {
* This holds the configuration settings for a web app-style
* Blockstack app
* @type {AppConfig}
* @private
*/
// required after sign in
// required after sign in
// TODO use this
function SessionData(options) {
_classCallCheck(this, SessionData);
@@ -1214,7 +1289,7 @@ var SessionData = exports.SessionData = function () {
// using this in place of
// window.localStorage.setItem(BLOCKSTACK_STORAGE_LABEL, JSON.stringify(userData))
// required after sign in
_createClass(SessionData, [{
key: 'getGaiaHubConfig',
@@ -1262,8 +1337,6 @@ var _authApp = require('./authApp');
var _authMessages = require('./authMessages');
var _authConstants = require('./authConstants');
var _storage = require('../storage');
var _utils = require('../utils');
@@ -1286,13 +1359,19 @@ function _classCallCheck(instance, Constructor) { if (!(instance instanceof Cons
* @type {UserSession}
*/
var UserSession = exports.UserSession = function () {
function UserSession(initialValue) {
function UserSession() {
var initialValue = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : new _appConfig.AppConfig();
_classCallCheck(this, UserSession);
var sessionOptions = {
appConfig: initialValue
};
this.session = new _sessionData.SessionData(sessionOptions);
if (initialValue instanceof _sessionData.SessionData) {
this.session = initialValue;
} else {
var sessionOptions = {
appConfig: initialValue
};
this.session = new _sessionData.SessionData(sessionOptions);
}
}
/* AUTHENTICATION */
@@ -1324,21 +1403,18 @@ var UserSession = exports.UserSession = function () {
* Redirects the user to the Blockstack browser to approve the sign in request
* given.
*
* The user is redirected to the `blockstackIDHost` if the `blockstack:`
* protocol handler is not detected. Please note that the protocol handler detection
* The user is redirected to the authenticator URL specified in the `AppConfig`
* if the `blockstack:` protocol handler is not detected.
* Please note that the protocol handler detection
* does not work on all browsers.
* @param {String} authRequest - the authentication request generated by `makeAuthRequest`
* @param {String} blockstackIDHost - the URL to redirect the user to if the blockstack
* protocol handler is not detected
* @return {void}
*/
}, {
key: 'redirectToSignInWithAuthRequest',
value: function redirectToSignInWithAuthRequest(authRequest) {
var blockstackIDHost = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : _authConstants.DEFAULT_BLOCKSTACK_HOST;
return (0, _authApp.redirectToSignInWithAuthRequestImpl)(authRequest, blockstackIDHost);
return (0, _authApp.redirectToSignInWithAuthRequestImpl)(this, authRequest);
}
/**
@@ -1578,7 +1654,7 @@ var UserSession = exports.UserSession = function () {
return UserSession;
}();
},{"../errors":14,"../storage":48,"../utils":49,"./appConfig":1,"./authApp":2,"./authConstants":3,"./authMessages":4,"./sessionData":9,"query-string":453}],11:[function(require,module,exports){
},{"../errors":14,"../storage":48,"../utils":49,"./appConfig":1,"./authApp":2,"./authMessages":4,"./sessionData":9,"query-string":453}],11:[function(require,module,exports){
'use strict';
Object.defineProperty(exports, "__esModule", {
@@ -8444,6 +8520,7 @@ function getFileImpl(caller, path, options) {
* the app private key
* @return {Promise} that resolves if the operation succeed and rejects
* if it failed
* @private
*/
function putFileImpl(caller, path, content, options) {
var defaults = {

3659
docs.json
View File

File diff suppressed because it is too large Load Diff

349
docs/index.html
View File

@@ -47,6 +47,42 @@
<ul class='list-reset py1-ul pl1'>
<li class='h5'><span>Instance members</span></li>
<li><a
href='#appconfigappdomain'
class='regular pre-open'>
#appDomain
</a></li>
<li><a
href='#appconfigscopes'
class='regular pre-open'>
#scopes
</a></li>
<li><a
href='#appconfigredirectpath'
class='regular pre-open'>
#redirectPath
</a></li>
<li><a
href='#appconfigmanifestpath'
class='regular pre-open'>
#manifestPath
</a></li>
<li><a
href='#appconfigcorenode'
class='regular pre-open'>
#coreNode
</a></li>
<li><a
href='#appconfigauthenticatorurl'
class='regular pre-open'>
#authenticatorURL
</a></li>
<li><a
href='#appconfigredirecturi'
class='regular pre-open'>
@@ -417,6 +453,319 @@ specify an app domain as the first argument.</p>
<div class='py1 quiet mt1 prose-big'>Instance Members</div>
<div class="clearfix">
<div class='border-bottom' id='appconfigappdomain'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>appDomain</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Blockstack apps are uniquely identified by their app domain.</p>
<div class='pre p1 fill-light mt0'>appDomain</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigscopes'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>scopes</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>An array of string representing permissions requested by the app.</p>
<div class='pre p1 fill-light mt0'>scopes</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigredirectpath'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>redirectPath</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Path on app domain to redirect users to after authentication. The
authentication response token will be postpended in a query.</p>
<div class='pre p1 fill-light mt0'>redirectPath</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigmanifestpath'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>manifestPath</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Path relative to app domain of app's manifest file.</p>
<p>This file needs to have CORS headers set so that it can be fetched
from any origin. Typically this means return the header <code>Access-Control-Allow-Origin: *</code>.</p>
<div class='pre p1 fill-light mt0'>manifestPath</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigcorenode'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>coreNode</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>The URL of Blockstack core node to use for this app. If this is
<code>null</code>, the core node specified by the user or default core node
will be used.</p>
<div class='pre p1 fill-light mt0'>coreNode</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigauthenticatorurl'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>authenticatorURL</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>The URL of a web-based Blockstack Authenticator to use in the event
the user doesn't have Blockstack installed on their machine. If this
is not specified, the current default in this library will be used.</p>
<div class='pre p1 fill-light mt0'>authenticatorURL</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='appconfigredirecturi'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">

19
documentation.yml
View File

@@ -4,18 +4,8 @@ toc:
Single sign on and authentication without third parties or remote servers.
[Read more about authentication](https://github.com/blockstack/blockstack.js/blob/master/src/auth/README.md)
- redirectToSignIn
- isSignInPending
- handlePendingSignIn
- loadUserData
- isUserSignedIn
- signUserOut
- makeAuthRequest
- generateAndStoreTransitKey
- redirectToSignInWithAuthRequest
- getAuthResponseToken
- verifyAuthResponse
- Blockstack
- AppConfig
- UserSession
- name: Profiles
description: |
Identity you own and control.
@@ -39,10 +29,5 @@ toc:
version. These features will be rolled out in future updates._
[Read more about storage](https://github.com/blockstack/blockstack.js/blob/master/src/storage/README.md)
- getFile
- putFile
- deleteFile
- encryptContent
- decryptContent
- getAppBucketUrl
- getUserAppFileUrl

76
src/auth/appConfig.js
View File

@@ -1,27 +1,78 @@
/* @flow */
import { DEFAULT_CORE_NODE, DEFAULT_SCOPE } from './authConstants'
import { DEFAULT_CORE_NODE, DEFAULT_SCOPE, DEFAULT_BLOCKSTACK_HOST } from './authConstants'
// modeled after what we have in Android
// https://github.com/blockstack/blockstack-android/blob/d70864acdc12f50bd90fb276853c523845e04e22/blockstack-sdk/src/main/java/org/blockstack/android/sdk/BlockstackConfig.kt#L14
/**
* Configuration data for the current app.
*
* On browser platforms, creating an instance of this
* class without any arguments will use
* `window.location.origin` as the app domain.
* On non-browser platforms, you need to
* specify an app domain as the first argument.
* @type {AppConfig}
*/
export class AppConfig {
/**
* Blockstack apps are uniquely identified by their app domain.
* @type {string}
*/
appDomain: string
/**
* An array of string representing permissions requested by the app.
* @type {[Array<string>}
*/
scopes: Array<string>
// this needs to be on appDomain so only accept paths
/**
* Path on app domain to redirect users to after authentication. The
* authentication response token will be postpended in a query.
* @type {string}
*/
redirectPath: string
// this needs to be on appDomain so only accept paths
/**
* Path relative to app domain of app's manifest file.
*
* This file needs to have CORS headers set so that it can be fetched
* from any origin. Typically this means return the header `Access-Control-Allow-Origin: *`.
* @type {string}
*/
manifestPath: string
// if null, use node passed by auth token v1.3 or otherwise core.blockstack.org
/**
* The URL of Blockstack core node to use for this app. If this is
* `null`, the core node specified by the user or default core node
* will be used.
* @type {string}
*/
coreNode: string
/**
* The URL of a web-based Blockstack Authenticator to use in the event
* the user doesn't have Blockstack installed on their machine. If this
* is not specified, the current default in this library will be used.
* @type {string}
*/
authenticatorURL: ?string
/**
* @param {string} appDomain - the app domain
* @param {Array<string>} scopes - permissions this app is requesting
* @param {string} redirectPath - path on app domain to redirect users to after authentication
* @param {string} manifestPath - path relative to app domain of app's manifest file
* @param {string} coreNode - override the default or user selected core node
* @param {string} authenticatorURL - the web-based fall back authenticator
*/
constructor(appDomain: string = window.location.origin,
scopes: Array<string> = DEFAULT_SCOPE.slice(),
redirectPath: string = '',
manifestPath: string = '/manifest.json',
coreNode: ?string = null) {
coreNode: ?string = null,
authenticatorURL: string = DEFAULT_BLOCKSTACK_HOST) {
this.appDomain = appDomain
this.scopes = scopes
this.redirectPath = redirectPath
@@ -32,12 +83,23 @@ export class AppConfig {
} else {
this.coreNode = coreNode
}
this.authenticatorURL = authenticatorURL
}
/**
* The location to which the authenticator should
* redirect the user.
* @returns {string} - URI
*/
redirectURI() : string {
return `${this.appDomain}${this.redirectPath}`
}
/**
* The location of the app's manifest file.
* @returns {string} - URI
*/
manifestURI() : string {
return `${this.appDomain}${this.manifestPath}`
}

16
src/auth/authApp.js
View File

@@ -31,17 +31,23 @@ const DEFAULT_PROFILE = {
* The user is redirected to the `blockstackIDHost` if the `blockstack:`
* protocol handler is not detected. Please note that the protocol handler detection
* does not work on all browsers.
* @param {UserSession} caller - the instance calling this method
* @param {String} authRequest - the authentication request generated by `makeAuthRequest`
* @param {String} blockstackIDHost - the URL to redirect the user to if the blockstack
* protocol handler is not detected
* @return {void}
* @private
*/
export function redirectToSignInWithAuthRequestImpl(authRequest: string,
blockstackIDHost: string =
DEFAULT_BLOCKSTACK_HOST) {
export function redirectToSignInWithAuthRequestImpl(caller: UserSession,
authRequest: string) {
const protocolURI = `${BLOCKSTACK_HANDLER}:${authRequest}`
const httpsURI = `${blockstackIDHost}?authRequest=${authRequest}`
let httpsURI = `${DEFAULT_BLOCKSTACK_HOST}?authRequest=${authRequest}`
if (caller.session && caller.session.appConfig
&& caller.session.appConfig.authenticatorURL) {
httpsURI = `${caller.session.appConfig.authenticatorURL}?authRequest=${authRequest}`
}
// If they're on a mobile OS, always redirect them to HTTPS site
if (/Android|webOS|iPhone|iPad|iPod|Opera Mini/i.test(navigator.userAgent)) {
@@ -88,7 +94,7 @@ export function redirectToSignInWithAuthRequestImpl(authRequest: string,
export function redirectToSignInImpl(caller: UserSession) {
const transitKey = caller.generateAndStoreTransitKey()
const authRequest = caller.makeAuthRequest(transitKey)
redirectToSignInWithAuthRequestImpl(authRequest)
redirectToSignInWithAuthRequestImpl(caller, authRequest)
}

4
src/auth/sessionData.js
View File

@@ -28,9 +28,6 @@ export class SessionData {
transitKey: ?string
// TODO use this
authenticatorURL: ?string
// using this in place of
// window.localStorage.setItem(BLOCKSTACK_STORAGE_LABEL, JSON.stringify(userData))
userData: ?any
@@ -40,6 +37,7 @@ export class SessionData {
* This holds the configuration settings for a web app-style
* Blockstack app
* @type {AppConfig}
* @private
*/
appConfig: ?AppConfig

17
src/auth/userSession.js
View File

@@ -15,10 +15,6 @@ import {
generateTransitKey
} from './authMessages'
import {
DEFAULT_BLOCKSTACK_HOST
} from './authConstants'
import {
decryptContentImpl,
encryptContentImpl,
@@ -83,18 +79,15 @@ export class UserSession {
* Redirects the user to the Blockstack browser to approve the sign in request
* given.
*
* The user is redirected to the `blockstackIDHost` if the `blockstack:`
* protocol handler is not detected. Please note that the protocol handler detection
* The user is redirected to the authenticator URL specified in the `AppConfig`
* if the `blockstack:` protocol handler is not detected.
* Please note that the protocol handler detection
* does not work on all browsers.
* @param {String} authRequest - the authentication request generated by `makeAuthRequest`
* @param {String} blockstackIDHost - the URL to redirect the user to if the blockstack
* protocol handler is not detected
* @return {void}
*/
redirectToSignInWithAuthRequest(authRequest: string,
blockstackIDHost: string
= DEFAULT_BLOCKSTACK_HOST) {
return redirectToSignInWithAuthRequestImpl(authRequest, blockstackIDHost)
redirectToSignInWithAuthRequest(authRequest: string) {
return redirectToSignInWithAuthRequestImpl(this, authRequest)
}
/**

1
src/storage/index.js
View File

@@ -385,6 +385,7 @@ export function getFileImpl(caller: UserSession, path: string, options?: {
* the app private key
* @return {Promise} that resolves if the operation succeed and rejects
* if it failed
* @private
*/
export function putFileImpl(caller: UserSession, path: string, content: string | Buffer, options?: {
encrypt?: boolean | string,