Merge "core.js: Cleaning up security docs."
diff --git a/src/security/access/doc.js b/src/security/access/doc.js
index 1420994..0efeb3f 100644
--- a/src/security/access/doc.js
+++ b/src/security/access/doc.js
@@ -47,11 +47,12 @@
* <p>These tags are meant to add a layer of interposition between the set of users
* (blessings, specifically) and the set of methods, much like "Roles" do in
* [Role Based Access Control]{@link (http://en.wikipedia.org/wiki/Role-based_access_control)}.
- * @property {map} val An ES6 map of string tags to
- * [AccessList]{@link module:vanadium.security.access.AccessList}
+ * @property {map} permissions An ES6 map of string tags to
+ * [AccessList]{@link module:vanadium.security.access.AccessList}.
* @name Permissions
* @constructor
- * @param {map} permissions An ES6 Map of string tags to AccessLists
+ * @param {map} permissions An ES6 Map of string tags to
+ * [AccessList]{@link module:vanadium.security.access.AccessList}.
* @memberof module:vanadium.security.access
*/
/*jshint ignore:end*/
@@ -61,7 +62,7 @@
* [Permissions]{@link module:vanadium.security.access.Permissions}.
* @name Tag
* @constructor
- * @param {string} val The value of the tag
+ * @param {string} val The value of the tag.
* @memberof module:vanadium.security.access
*/
/**
@@ -72,13 +73,13 @@
* @memberof module:vanadium.security.access
*/
/**
- * Used for operations that return debugging information about the object
+ * Used for operations that return debugging information about the object.
* @name Debug
* @type module:vanadium.security.access.Tag
* @memberof module:vanadium.security.access
*/
/**
- * Used for operations that do not mutate the state of the object
+ * Used for operations that do not mutate the state of the object.
* @name Read
* @type module:vanadium.security.access.Tag
* @memberof module:vanadium.security.access
@@ -90,7 +91,7 @@
* @memberof module:vanadium.security.access
*/
/**
- * Used for operations that involve namespace navigation
+ * Used for operations that involve namespace navigation.
* @name Resolve
* @type module:vanadium.security.access.Tag
* @memberof module:vanadium.security.access
@@ -114,26 +115,25 @@
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
- * @param {array} validBlessings A list of strings that represent valid
- * blessings
- * @param {array} rejectedBlessings A list of blessings that are rejected.
- * The array has [RejectedBlessings]
- * {@link module:vanadium.security.RejectedBlessings}.
+ * @param {string[]} validBlessings A list of strings that represent valid
+ * blessings.
+ * @param {module:vanadium.security.RejectedBlessing[]} rejectedBlessings A
+ * list of blessings that are rejected.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary Error that means that no blessings have access to the specified
- * access tag (e.g. No Read Access or No Admin Access)
+ * access tag (e.g. No Read Access or No Admin Access).
* @name NoPermissionsError
* @memberof module:vanadium.security.access
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
- * @param {array} validBlessings A list of strings that represent valid
- * blessings
- * @param {array} rejectedBlessings A list of blessings that are rejected.
- * The array has [RejectedBlessings]
+ * @param {string[]} validBlessings A list of strings that represent valid
+ * blessings.
+ * @param {module:vanadium.security.RejectedBlessing[]} rejectedBlessings A list
+ * of blessings that are rejected.
* @param {module:vanadium.security.access.Tag} tag Access tag.
* {@link module:vanadium.security.RejectedBlessings}.
* @param {...*} params A list of parameters to include in the error message.
diff --git a/src/security/access/permissions-authorizer.js b/src/security/access/permissions-authorizer.js
index 148d40c..6c4e1c4 100644
--- a/src/security/access/permissions-authorizer.js
+++ b/src/security/access/permissions-authorizer.js
@@ -34,7 +34,8 @@
* @name permissionsAuthorizer
* @param {module:vanadium.security.access.Permissions} perms The set of
* permission to apply.
- * @param {function} type The type of tags that this authorizer understands.
+ * @param {function} type The type constructor function of tags that this
+ * authorizer understands.
* @return {module:vanadium.security.Authorize} An authorizer that applies
* the perms.
*/
diff --git a/src/security/blessings.js b/src/security/blessings.js
index 22e4544..2cb3f51 100644
--- a/src/security/blessings.js
+++ b/src/security/blessings.js
@@ -42,6 +42,7 @@
/**
* Decrements the reference count on the Blessings. When the reference count
* goes to zero, the Blessings will be removed from the cache in the go code.
+ * @param {module:vanadium.context.Context} ctx A context.
*/
Blessings.prototype.release = function(ctx) {
this._count--;
diff --git a/src/security/blessingstore.js b/src/security/blessingstore.js
index 4aef3dc..137d788 100644
--- a/src/security/blessingstore.js
+++ b/src/security/blessingstore.js
@@ -15,8 +15,8 @@
/**
* A callback that is called with either an error or a
* [Blessings]{@link module:vanadium.security~Blessings} object.
- * @callback module:vanadium.security.BlessingStore~blessingsCb
- * @param {Error} err If set, the error that occured
+ * @callback module:vanadium.security~BlessingStore~blessingsCb
+ * @param {Error} err If set, the error that occurred.
* @param {module:vanadium.security~Blessings} blessings The blessings result.
*/
/**
@@ -40,9 +40,9 @@
* @param {module:vanadium.context.Context} ctx The context.
* @param {module:vanadium.security~Blessings} blessings The blessings object.
* @param {string} pattern The blessing match pattern.
- * @param {module:vanadium.security.BlessingStore~blessingsCb} cb an optional
+ * @param {module:vanadium.security~BlessingStore~blessingsCb} cb an optional
* callback that will return the blessing handle.
- * @return {Promise<module:vanadium.security~Blessings>} a promise that will
+ * @return {Promise<module:vanadium.security~Blessings>} A promise that will
* be resolved with the blessing handle.
*/
BlessingStore.prototype.set = function(
diff --git a/src/security/call.js b/src/security/call.js
index f84f809..daf095f 100644
--- a/src/security/call.js
+++ b/src/security/call.js
@@ -12,8 +12,8 @@
/**
* @summary Call defines the state available for authorizing a principal.
* @name SecurityCall
- * @property {string} method The method being invoked
- * @property {string} suffix The object name suffix of the request
+ * @property {string} method The method being invoked.
+ * @property {string} suffix The object name suffix of the request.
* @property {module:vanadium.security~Blessings} localBlessings The blessings
* bound to the local end.
* @property {string} localBlessingStrings The validated names for the local
@@ -22,8 +22,8 @@
* bound to the remote end.
* @property {string} remoteBlessingStrings The validated names for the remote
* end.
- * @property {string} localEndpoint The endpoint string for the local end
- * @property {string} remoteEndpoint The endpoint string for the remote end
+ * @property {string} localEndpoint The endpoint string for the local end.
+ * @property {string} remoteEndpoint The endpoint string for the remote end.
* @inner
* @memberof module:vanadium.security
*/
diff --git a/src/security/caveat-validator-registry.js b/src/security/caveat-validator-registry.js
index 47d34c6..198a7e8 100644
--- a/src/security/caveat-validator-registry.js
+++ b/src/security/caveat-validator-registry.js
@@ -58,13 +58,11 @@
*/
/**
- * Register a caveat validation function
+ * Register a caveat validation function.
* @param {module:vanadium.security.CaveatDescriptor} cavDesc The caveat
* description.
- * See security/types.vdl
* @param {module:vanadium.security.CaveatValidationFunction} validateFn
* The validation function.
- * e.g. function validateCaveatA(param) { ...
*/
CaveatValidatorRegistry.prototype.register = function(cavDesc, validateFn) {
this.validators.set(
@@ -94,7 +92,7 @@
};
/**
- * CaveatValidator is a helper object representating a specific caveat
+ * CaveatValidator is a helper object representing a specific caveat
* description and function pair.
* @private
*/
diff --git a/src/security/caveats.js b/src/security/caveats.js
index 22b820b..df780e0 100644
--- a/src/security/caveats.js
+++ b/src/security/caveats.js
@@ -18,8 +18,8 @@
* that requires validation by the validation function correponding
* to cavDesc and uses the provided parameters.
* @param {module:vanadium.security.CaveatDescriptor} cavDesc The type of
- * caveat that is being created
- * @param {*} data The data for the caveat
+ * caveat that is being created.
+ * @param {*} data The data for the caveat.
* @return module:vanadium.security.Caveat
* @memberof module:vanadium.security
*/
@@ -37,7 +37,7 @@
/**
* createExpiryCaveat returns a [Caveat]{@link module:vanadium.security.Caveat}
* that validates iff the current time is before t
- * @param {date} expiryTime The time the caveat expires
+ * @param {Date} expiryTime The time the caveat expires.
* @returns module:vanadium.security.Caveat
* @memberof module:vanadium.security
*/
@@ -49,7 +49,7 @@
* createMethodCaveat returns a [Caveat]{@link module:vanadium.security.Caveat}
* that validates iff the method being invoked by the peer is listed in
* methods array passed in.
- * @param {array<string>} methods The methods that are allowed.
+ * @param {string[]} methods The methods that are allowed.
* @returns module:vanadium.security.Caveat
* @memberof module:vanadium.security
*/
@@ -64,4 +64,3 @@
* @returns module:vanadium.security.Caveat
* @memberof module:vanadium.security
*/
-
diff --git a/src/security/doc.js b/src/security/doc.js
index ff283bc..2bb372e 100644
--- a/src/security/doc.js
+++ b/src/security/doc.js
@@ -21,8 +21,8 @@
*
* @name BlessingPattern
* @constructor
- * @property {string} val The blessing pattern
- * @param {string} pattern The pattern
+ * @property {string} val The blessing pattern.
+ * @param {string} pattern The pattern.
* @memberof module:vanadium.security
*/
/**
@@ -31,14 +31,14 @@
* validation function.
* @name CaveatDescriptor
* @memberof module:vanadium.security
- * @property {module:vanadium.uniqueId.Id.Id} id The uniqe id for the caveat
- * validation function
+ * @property {module:vanadium.uniqueId.Id} id The unique id for the caveat
+ * validation function.
* @property {module:vanadium.vdl.Type} paramType The type of
* the data that will be passed into the function.
* @constructor
- * @param {object} descriptor The descriptor
- * @param {module:vanadium.uniqueId.Id.Id} descriptor.id The unique id for the
- * caveat validation funciton
+ * @param {object} descriptor The descriptor.
+ * @param {module:vanadium.uniqueId.Id} descriptor.id The unique id for the
+ * caveat validation function.
* @param {module:vanadium.vdl.Type} descriptor.paramType The type of
* the data that will be passed into the function.
*/
@@ -47,13 +47,13 @@
* @name RejectedBlessing
* @memberof module:vanadium.security
* @property {string} blessing The blessing that failed validation.
- * @property {module:vanadium.error.VanadiumError} inValue.err The err that
- * occured
+ * @property {module:vanadium.verror.VanadiumError} inValue.err The err that
+ * occurred.
* @constructor
* @param {object} inValue
* @param {string} inValue.blessing The blessing that failed validation.
- * @param {module:vanadium.error.VanadiumError} inValue.err The err that
- * occured
+ * @param {module:vanadium.verror.VanadiumError} inValue.err The err that
+ * occurred.
*/
/**
* Represents a caveat that will always succeed or fail. The data
@@ -81,23 +81,6 @@
* @memberof module:vanadium.security
*/
/**
- * @summary Caveat is a condition on the validity of a blessing/discharge.
- * @description These conditions are provided when asking a principal to create
- * a blessing/discharge and are verified when extracting blessings.
- * @name Caveat
- * @memberof module:vanadium.security
- * @constructor
- * @property {module:vanadium.uniqueId.Id} id The identifier of the caveat
- * caveat validation function
- * @property {uint8array} paramVom The vom encoded bytes of the parameters to
- * be provided to the validation function.
- * @param {object} o The json object to construct the caveat from.
- * @param {module:vanadium.uniqueId.Id} o.id The identifier of the caveat
- * caveat validation function
- * @param {uint8array} o.paramVom The vom encoded bytes of the parameters to
- * be provided to the validation function.
- */
-/**
* PeerBlessingsCaveat represents a caveat that validates iff the peer being
* communicated with (local end of the call) has a blessing name matching at
* least one of the patterns in the list. An empty list implies that the caveat
@@ -108,7 +91,24 @@
* @memberof module:vanadium.security
*/
/**
- * @summary An error that means that no caveat has been registered
+ * @summary Caveat is a condition on the validity of a blessing/discharge.
+ * @description These conditions are provided when asking a principal to create
+ * a blessing/discharge and are verified when extracting blessings.
+ * @name Caveat
+ * @memberof module:vanadium.security
+ * @constructor
+ * @property {module:vanadium.uniqueId.Id} id The identifier of the caveat
+ * validation function.
+ * @property {uint8array} paramVom The vom encoded bytes of the parameters to
+ * be provided to the validation function.
+ * @param {object} o The json object to construct the caveat from.
+ * @param {module:vanadium.uniqueId.Id} o.id The identifier of the caveat
+ * validation function.
+ * @param {uint8array} o.paramVom The vom encoded bytes of the parameters to
+ * be provided to the validation function.
+ */
+/**
+ * @summary An error that means that no caveat has been registered.
* @name CaveatNotRegisteredError
* @memberof module:vanadium.security
* @constructor
@@ -140,7 +140,7 @@
* created in.
* @param {module:vanadium.uniqueId.Id} id The id of the caveat with the
* problem.
- * @param {module:vanadium.vdl.Type} got The type passed in
+ * @param {module:vanadium.vdl.Type} got The type passed in.
* @param {module:vanadium.vdl.Type} want The type passed expected.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
@@ -165,7 +165,7 @@
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
- * @param {module:vanadium.error.VanadiumError} err The error that occured.
+ * @param {module:vanadium.verror.VanadiumError} err The error that occurred.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
@@ -190,8 +190,8 @@
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
- * @param {date} expiry The time the caveat expires
- * @param {date} now The current time
+ * @param {date} expiry The time the caveat expires.
+ * @param {date} now The current time.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
@@ -227,16 +227,16 @@
*/
/**
* @summary An error that means a remote principal is not authorized by a local
- * principal
+ * principal.
* @name AuthorizationFailedError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
- * @param {array<string>} remoteBlessings Remote blessings
+ * @param {array<string>} remoteBlessings Remote blessings.
* @param {array<module:vanadium.security.RejectedBlessing>} rejectedBlessings
- * Remote rejected blessing
- * @param {array<string>} localBlessings Local blessings
+ * Remote rejected blessing.
+ * @param {array<string>} localBlessings Local blessings.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
@@ -245,17 +245,11 @@
* @callback Authorize
* @param {module:vanadium.context.Context} context The context of the
* rpc.
- * @param {module:vanadium.security.Authorize~callback} cb The callback to
+ * @param {module:vanadium~voidCb} cb The callback to
* call with the result if the rpc is asynchronous. This can be ignored
* if the Authorizer returns a promise.
- * @return {Promise} A Promise that will be resolved if the authorization
+ * @return {Promise<void>} A Promise that will be resolved if the authorization
* succeeded and rejected if it failed. If no promise is returned, then
* the callback must be called.
* @memberof module:vanadium.security
*/
-/**
- * Callback passed into Authorize
- * @callback Authorize~callback
- * @param {Error} err If set, the reason that the authorization failed.
- * @memberof module:vanadium.security
- */
diff --git a/src/security/principal.js b/src/security/principal.js
index f2d9cac..357ff95 100644
--- a/src/security/principal.js
+++ b/src/security/principal.js
@@ -15,17 +15,17 @@
/**
* A callback that is called with either an error or a
* [Blessings]{@link module:vanadium.security~Blessings} object.
- * @callback Blessings~cb
- * @param {Error} err If set, the error that occured
+ * @callback module:vanadium.security~Principal~blessingsCb
+ * @param {Error} err If set, the error that occurred
* @param {module:vanadium.security~Blessings} blessings The blessings result.
*/
/**
* @summary Principal represents an entity capable of making or receiving RPCs.
* @description <p>Principal represents an entity capable of making or receiving
* RPCs. Principals have a unique (public, private) key pair, have blessings
- * bound to them and can bless other principals.</p>.
- * <p>This constructor should not be used explicitly. Instead, use
- * {@link module:vanadium~Runtime#principal}
+ * bound to them and can bless other principals.</p>
+ * <p>This constructor should not be used explicitly. Instead, use the
+ * principal property on the [runtime]{@link module:vanadium~Runtime}.
* @constructor
* @property {module:vanadium.security~Blessings} defaultBlessings The default
* blessings for this principal.
@@ -50,14 +50,16 @@
* <pre>
* bless(ctx, <other public key>, <google/alice, v23/alice>, 'friend', ...)
* </pre>
- * @param {module:vanadium.context.Context} ctx The context
- * @param {string} publicKey The public key to bless
- * @param {module:vanadium.security~Blessings} blessing The blessings
- * @param {string} extension the extension for the blessing.
- * @param {...module:vanadium.security.Caveat} caveats an array of Cavaeats to
+ * @param {module:vanadium.context.Context} ctx The context.
+ * @param {string} publicKey The public key to bless.
+ * @param {module:vanadium.security~Blessings} blessing The blessings.
+ * @param {string} extension The extension for the blessing.
+ * @param {...module:vanadium.security.Caveat} caveats An array of Caveats to
* restrict the blessing.
- * @param {Blessings~cb} cb an optional callback that will return the blessing
- * @return {Promise} a promise that will be resolved with the blessing
+ * @param {module:vanadium.security~Principal~blessingsCb} cb An optional
+ * callback that will return the blessing.
+ * @return {Promise<module:vanadium.security~Blessings>} A promise that will be
+ * resolved with the blessing.
*/
Principal.prototype.bless = function(ctx, publicKey, blessings,
extension, firstCaveat /*, ...moreCaveats, cb*/) {
@@ -97,12 +99,14 @@
/**
* BlessSelf creates a blessing with the provided name for this principal.
- * @param {module:vanadium.context.Context} ctx The context
- * @param {string} name the name for the blessing.
- * @param {...module:vanadium.security.Caveat} caveats an array of Cavaeats to
+ * @param {module:vanadium.context.Context} ctx The context.
+ * @param {string} name The name for the blessing.
+ * @param {...module:vanadium.security.Caveat} caveats An array of Caveats to
* restrict the blessing.
- * @param {Blessings~cb} cb an optional callback that will return the blessing
- * @return {Promise} a promise that will be resolved with the blessing
+ * @param {module:vanadium.security~Principal~blessingsCb} cb An optional
+ * callback that will return the blessing.
+ * @return {Promise<module:vanadium.security~Blessings>} A promise that will be
+ * resolved with the blessing.
*/
Principal.prototype.blessSelf = function(ctx, name /*, ...caveats, cb*/) {
// Extract the callback.
@@ -133,11 +137,11 @@
/**
* Add the provided blessing as a root.
- * @param {module:vanadium.context.Context} ctx The context
- * @param {module:vanadium.security~Blessings} blessings The blessings object
- * @param {Blessings~cb} cb an optional callback that will return the blessing
- * handle
- * @return {Promise} a promise (resolves with no value)
+ * @param {module:vanadium.context.Context} ctx The context.
+ * @param {module:vanadium.security~Blessings} blessings The blessings object.
+ * @param {module:vanadium~voidCb} cb If provided, the function
+ * will be called on completion.
+ * @return {Promise<void>} A promise that will be resolved/reject on completion.
*/
Principal.prototype.addToRoots = function(
ctx, blessings, cb) {
