The Ims class wraps the IMS API.
The ConfigCliContext class stores IMS contexts for the Adobe I/O CLI in the local file
system using the Adobe I/O Core Configuration Library.
objectobjectPromise.<ValidationResult>aio-lib-ims](#module_aio-lib-ims)
**See**: [`Ims`](#ims)
+
+
+### aio-lib-ims.ValidationCache
+**Kind**: static property of [aio-lib-ims](#module_aio-lib-ims)
+**See**: [`ValidationCache`](#ValidationCache)
### aio-lib-ims.ACCESS\_TOKEN
@@ -195,7 +216,7 @@ The `Ims` class wraps the IMS API.
**Kind**: global class
* [Ims](#Ims)
- * [new Ims(env)](#new_Ims_new)
+ * [new Ims(env, cache)](#new_Ims_new)
* _instance_
* [.getApiUrl(api)](#Ims+getApiUrl) ⇒ string
* [.getSusiUrl(clientId, scopes, callbackUrl, state)](#Ims+getSusiUrl) ⇒ string
@@ -205,7 +226,9 @@ The `Ims` class wraps the IMS API.
* [.getAccessTokenByClientCredentials(clientId, clientSecret, orgId, scopes)](#Ims+getAccessTokenByClientCredentials) ⇒ Promise
* [.exchangeJwtToken(clientId, clientSecret, signedJwtToken)](#Ims+exchangeJwtToken) ⇒ Promise
* [.invalidateToken(token, clientId, clientSecret)](#Ims+invalidateToken) ⇒ Promise
+ * [.validateTokenAllowList(token, allowList)](#Ims+validateTokenAllowList) ⇒ Promise
* [.validateToken(token, [clientId])](#Ims+validateToken) ⇒ object
+ * [._validateToken(token, [clientId])](#Ims+_validateToken) ⇒ object
* [.getOrganizations(token)](#Ims+getOrganizations) ⇒ object
* [.toTokenResult(token)](#Ims+toTokenResult) ⇒ Promise
* _static_
@@ -213,13 +236,14 @@ The `Ims` class wraps the IMS API.
-### new Ims(env)
+### new Ims(env, cache)
Creates a new IMS connector instance for the stage or prod environment
| Param | Type | Description |
| --- | --- | --- |
| env | string | The name of the environment. `prod` and `stage` are the only values supported. `prod` is default and any value other than `prod` or `stage` it is assumed to be the default value of `prod`. If not set, it will get the global cli env value. See https://github.com/adobe/aio-lib-env (which defaults to `prod` as well if not set) |
+| cache | [ValidationCache](#ValidationCache) | The cache instance to use. |
@@ -297,7 +321,7 @@ Request the access token for the given client providing the access
grant in the
Request an access token of the Client Credentials Grant Type.
**Kind**: instance method of [Ims](#Ims)
-**Returns**: Promise - a promise resolving to a tokens object as described in the
[toTokenResult](toTokenResult) or rejects to an error message.
+**Returns**: Promise - a promise resolving to a token object as described in the
[ClientCredentialsResponse](#ClientCredentialsResponse) or rejects to an error message.
| Param | Type | Description |
| --- | --- | --- |
@@ -334,10 +358,23 @@ Invalidates the given token. If the token is a refresh token, all the
access tok
| clientId | string | the client id |
| clientSecret | string | the client secret |
+
+
+### ims.validateTokenAllowList(token, allowList) ⇒ Promise
+Validates the given token against an allow list.
Optional: If a cache is provided, the token will be validated against the cache first.
Note: The cache uses the returned status key to determine if the result should be cached. This is not returned
to the user.
+
+**Kind**: instance method of [Ims](#Ims)
+**Returns**: Promise - Promise that resolves with the ims validation result
+
+| Param | Type | Description |
+| --- | --- | --- |
+| token | string | the token to validate |
+| allowList | Array.<string> | the allow list to validate against |
+
### ims.validateToken(token, [clientId]) ⇒ object
-Verifies a given token.
+Validates the given token.
**Kind**: instance method of [Ims](#Ims)
**Returns**: object - the server response
@@ -347,6 +384,19 @@ Verifies a given token.
| token | string | the access token |
| [clientId] | string | the client id, optional |
+
+
+### ims.\_validateToken(token, [clientId]) ⇒ object
+Verifies a given token, returns a status which can be used to determine cache status if this function is passed to the validation cache.
+
+**Kind**: instance method of [Ims](#Ims)
+**Returns**: object - Status code and the server response
+
+| Param | Type | Description |
+| --- | --- | --- |
+| token | string | the access token |
+| [clientId] | string | the client id, optional |
+
### ims.getOrganizations(token) ⇒ object
@@ -383,6 +433,86 @@ Creates an instance of the `Ims` class deriving the instance's
environment from
| --- | --- | --- |
| token | string | The access token from which to extract the environment to setup the `Ims` instancee. |
+
+
+## ValidationCache
+**Kind**: global class
+
+* [ValidationCache](#ValidationCache)
+ * [new ValidationCache()](#new_ValidationCache_new)
+ * [new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)](#new_ValidationCache_new)
+ * [.validateWithCache(validationFunction, ...validationParams)](#ValidationCache+validateWithCache) ⇒ Promise.<object>
+
+
+
+### new ValidationCache()
+A class to cache valid or invalid results. Internally two separate cache entries are
maintained. Each cache entry is about 66Bytes big.
+
+
+
+### new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)
+Creates a new LRU cache instance.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| maxAge | number | The maximum age in milliseconds of cache validity. |
+| maxValidEntries | number | The maximum number of valid entries that can be contained in the cache. |
+| maxInvalidEntries | number | The maximum number of invalid entries that can be contained in the cache. |
+
+
+
+### validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ Promise.<object>
+Applies a validation function and caches the result. If there is a cache entry
available returns the cached result without calling the validation function.
The cache key is computed from the validation params
+
+**Kind**: instance method of [ValidationCache](#ValidationCache)
+**Returns**: Promise.<object> - validation result
+
+| Param | Type | Description |
+| --- | --- | --- |
+| validationFunction | [ValidationFunction](#ValidationFunction) | a function that returns an object of the form `{ status, message }` |
+| ...validationParams | string | parameters for the validationFunction, must be at least one |
+
+
+
+## ValidationCache
+**Kind**: global class
+
+* [ValidationCache](#ValidationCache)
+ * [new ValidationCache()](#new_ValidationCache_new)
+ * [new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)](#new_ValidationCache_new)
+ * [.validateWithCache(validationFunction, ...validationParams)](#ValidationCache+validateWithCache) ⇒ Promise.<object>
+
+
+
+### new ValidationCache()
+A class to cache valid or invalid results. Internally two separate cache entries are
maintained. Each cache entry is about 66Bytes big.
+
+
+
+### new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)
+Creates a new LRU cache instance.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| maxAge | number | The maximum age in milliseconds of cache validity. |
+| maxValidEntries | number | The maximum number of valid entries that can be contained in the cache. |
+| maxInvalidEntries | number | The maximum number of invalid entries that can be contained in the cache. |
+
+
+
+### validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ Promise.<object>
+Applies a validation function and caches the result. If there is a cache entry
available returns the cached result without calling the validation function.
The cache key is computed from the validation params
+
+**Kind**: instance method of [ValidationCache](#ValidationCache)
+**Returns**: Promise.<object> - validation result
+
+| Param | Type | Description |
+| --- | --- | --- |
+| validationFunction | [ValidationFunction](#ValidationFunction) | a function that returns an object of the form `{ status, message }` |
+| ...validationParams | string | parameters for the validationFunction, must be at least one |
+
## ConfigCliContext
@@ -607,3 +737,36 @@ Returns the decoded token value as JavaScript object.
| --- | --- | --- |
| token | string | The token to decode and extract the token value from |
+
+
+## ClientCredentialsResponse : object
+**Kind**: global typedef
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| access_token | string | The access token issued by IMS |
+| token_type | string | The type of the token (in this case 'bearer') |
+| expires_in | number | The lifetime in seconds of the access token |
+
+
+
+## ValidationResult : object
+**Kind**: global typedef
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| status | number | validation response status code, e.g 200, 401, 403, ... |
+| message | string | validation message, e.g. reason of failed validation |
+
+
+
+## ValidationFunction ⇒ [Promise.<ValidationResult>](#ValidationResult)
+**Kind**: global typedef
+**Returns**: [Promise.<ValidationResult>](#ValidationResult) - validation result
+
+| Param | Type | Description |
+| --- | --- | --- |
+| ...params | string | validation params used for building the cache key (at least one) |
+
diff --git a/src/ValidationCache.js b/src/ValidationCache.js
index 208de33..769226f 100644
--- a/src/ValidationCache.js
+++ b/src/ValidationCache.js
@@ -96,7 +96,7 @@ class ValidationCache {
/**
* @param {Array} params
- * @returns
+ * @returns {string} the computed hash key
* @memberof ValidationCache
* @private
*/
diff --git a/src/ims.js b/src/ims.js
index 486127d..e4fd94c 100644
--- a/src/ims.js
+++ b/src/ims.js
@@ -45,6 +45,13 @@ const CLIENT_SECRET = 'client_secret'
/** The constant string `scope`. */
const SCOPE = 'scope'
+/**
+ * @typedef {object} ClientCredentialsResponse
+ * @property {string} access_token The access token issued by IMS
+ * @property {string} token_type The type of the token (in this case 'bearer')
+ * @property {number} expires_in The lifetime in seconds of the access token
+ */
+
/**
* Send the request.
*
@@ -369,8 +376,8 @@ class Ims {
* @param {string} clientSecret The Client Secret proving client ID ownership
* @param {string} orgId the IMS org Id
* @param {Array