blob: 2b35ca755d21d00a73cb0f1d01c59ce16c9c50b4 [file] [log] [blame]
// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
/*
* A file for JSDocs for vdl generated files in security
*/
/**
* @summary BlessingPattern is a pattern that is matched by specific blessings.
* @description
* <p>A pattern can either be a blessing (slash-separated human-readable string)
* or a blessing ending in "/$". A pattern ending in "/$" is matched exactly
* by the blessing specified by the pattern string with the "/$" suffix
* stripped out. For example, the pattern "a/b/c/$" is matched by exactly by the
* blessing "a/b/c".</p>
*
* <p>A pattern not ending in "/$" is more permissive, and is also matched by
* blessings that are extensions of the pattern (including the pattern itself).
* For example, the pattern "a/b/c" is matched by the blessings "a/b/c",
* "a/b/c/x", "a/b/c/x/y", etc.</p>
*
* @name BlessingPattern
* @constructor
* @property {string} val The blessing pattern.
* @param {string} pattern The pattern.
* @memberof module:vanadium.security
*/
/**
* @summary A descriptor that is used to associate a caveat validation function
* (addressed by a globally unique identifier) and the data needed by the
* validation function.
* @name CaveatDescriptor
* @memberof module:vanadium.security
* @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} 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.
*/
/**
* @summary An explanation of why a blessing failed validation.
* @name RejectedBlessing
* @memberof module:vanadium.security
* @property {string} blessing The blessing that failed validation.
* @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.verror.VanadiumError} inValue.err The err that
* occurred.
*/
/**
* Represents a caveat that will always succeed or fail. The data
* should be a boolean.
* @name ConstCaveat
* @type module:vanadium.security.CaveatDescriptor
* @const
* @memberof module:vanadium.security
*/
/**
* Represents a caveat that validates iff the current time is no later
* than the specified time. The data should be a date.
* @name ExpiryCaveat
* @type module:vanadium.security.CaveatDescriptor
* @const
* @memberof module:vanadium.security
*/
/**
* Represents a caveat that validates iff the method being invoked is
* included in the array of strings passed in. An empty list means that
* the holder cannot invoke any methods.
* @name MethodCaveat
* @type module:vanadium.security.CaveatDescriptor
* @const
* @memberof module:vanadium.security
*/
/**
* 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
* is invalid.
* @name PeerBlessingsCaveat
* @type module:vanadium.security.CaveatDescriptor
* @const
* @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
* 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
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @param {module:vanadium.uniqueId.Id} id The id not registered.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means that the caveat cannot have a param type of any.
* @name CaveatParamAnyError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @param {module:vanadium.uniqueId.Id} id The id of the caveat with the
* problem.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means that the type of the passed in data does not
* match the type expected by the descriptor.
* @name CaveatParamTypeMismatchError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* 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} want The type passed expected.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means that the param type could not be encoded.
* @name CaveatParamCodingError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @param {module:vanadium.uniqueId.Id} id The id of the caveat with the
* problem.
* @param {module:vanadium.vdl.Type} got The type of the caveat data.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means that the caveat didn't validate.
* @name CaveatValidationError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @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
*/
/**
* @summary An error that means that the
* [ConstCaveat]{@link module:vanadium.security.ConstCaveat}
* failed to validate.
* @name ConstCaveatValidationError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means that the
* [ExpiryType]{@link module:vanadium.security.ExpiryCaveat} failed to
* validate.
* @name ExpiryCaveatValidationError
* @memberof module:vanadium.security
* @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 {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means that the
* [MethodCaveat]{@link module:vanadium.security.MethodCaveat} failed to
* validate.
* @name MethodCaveatValidationError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @param {string} method The method that was being invoked.
* @param {array<string>} validMethods The methods that are allowed by
* the caveat.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means that the
* [PeerBlessingsCaveat]{@link module:vanadium.security.PeerBlessingsCaveat}
* failed to validate.
* @name PeerBlessingsCaveatValidationError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @param {string} method The method that was being invoked.
* @param {array<string>} validMethods The methods that are allowed by
* the caveat.
* @param {...*} params A list of parameters to include in the error message.
* @augments module:vanadium.verror.VanadiumError
*/
/**
* @summary An error that means a remote principal is not authorized by a local
* principal.
* @name AuthorizationFailedError
* @memberof module:vanadium.security
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
* @param {module:vanadium.security~SecurityCall} secCall The security call
* to validate.
* @param {array<string>} remoteBlessings Remote blessings.
* @param {array<module:vanadium.security.RejectedBlessing>} rejectedBlessings
* 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
*/
/**
* A function that returns an error if the operation is not authorized.
* @callback Authorize
* @param {module:vanadium.context.Context} ctx The context of the
* rpc.
* @param {module:vanadium.security~SecurityCall} secCall A SecurityCall.
* @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<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
*/