feat: allow audiences helper to return a single string audience

Author: panva

docs/README.md

@@ -1471,7 +1471,7 @@ true
 
 [draft-ietf-oauth-resource-indicators-05](https://tools.ietf.org/html/draft-ietf-oauth-resource-indicators-05) - Resource Indicators for OAuth 2.0  
 
-Enables the use of `resource` parameter for the authorization and token endpoints. In order for the feature to be any useful you must also use the `audiences` helper function to validate the resource(s) and transform it to the token audience.   
+Enables the use of `resource` parameter for the authorization and token endpoints. In order for the feature to be any useful you must also use the `audiences` helper function to validate the resource(s) and transform it to the Access Token audience.   
 
 
 
@@ -1528,10 +1528,7 @@ This example will
   },
   formats: {
     AccessToken(ctx, token) {
-      if (Array.isArray(token.aud)) {
-        return 'jwt';
-      }
-      return 'opaque';
+      return token.aud ? 'jwt' : 'opaque';
     }
   },
   // ...
@@ -1628,7 +1625,7 @@ _**default value**_:
 
 ### audiences
 
-Helper used by the OP to push additional audiences to issued Access and ClientCredentials Tokens. The return value should either be falsy to omit adding additional audiences or an array of strings to push.  
+Helper used by the OP to set an audience to issued Access Tokens. The return value should either be falsy use the default audience (client) or an array of string aud values, or a single string aud value.  
 
 
 _**default value**_:
@@ -2026,21 +2023,18 @@ Configure `formats`:
 { AccessToken: 'paseto' }
 ```
 </details>
-<a name="formats-to-dynamically-decide-on-the-format-used-e-g-only-if-it-is-intended-for-more-audiences"></a><details>
-  <summary>(Click to expand) To dynamically decide on the format used, e.g. only if it is intended for more audiences</summary>
+<a name="formats-to-dynamically-decide-on-the-format-used-e-g-only-if-it-is-intended-for-a-resource"></a><details>
+  <summary>(Click to expand) To dynamically decide on the format used, e.g. only if it is intended for a resource</summary>
   <br>
 
 
-Configure `formats`:
+server Configure `formats`:
 
 
 ```js
 {
   AccessToken(ctx, token) {
-    if (Array.isArray(token.aud)) {
-      return 'jwt';
-    }
-    return 'opaque';
+    return token.aud ? 'jwt' : 'opaque';
   }
 }
 ```

lib/helpers/defaults.js

@@ -995,7 +995,7 @@ const DEFAULTS = {
      *
      * description: Enables the use of `resource` parameter for the authorization and token
      *   endpoints. In order for the feature to be any useful you must also use the `audiences`
-     *   helper function to validate the resource(s) and transform it to the token audience.
+     *   helper function to validate the resource(s) and transform it to the Access Token audience.
      *
      * example: Example use
      * This example will
@@ -1042,11 +1042,7 @@ const DEFAULTS = {
      *   },
      *   formats: {
      *     AccessToken(ctx, token) {
-     *       if (Array.isArray(token.aud)) {
-     *         return 'jwt';
-     *       }
-     *
-     *       return 'opaque';
+     *       return token.aud ? 'jwt' : 'opaque';
      *     }
      *   },
      *   // ...
@@ -1211,17 +1207,14 @@ const DEFAULTS = {
    * { AccessToken: 'paseto' }
    * ```
    *
-   * example: To dynamically decide on the format used, e.g. only if it is intended for more audiences
+   * example: To dynamically decide on the format used, e.g. only if it is intended for a resource
+   *   server
    *
    * Configure `formats`:
    * ```js
    * {
    *   AccessToken(ctx, token) {
-   *     if (Array.isArray(token.aud)) {
-   *       return 'jwt';
-   *     }
-   *
-   *     return 'opaque';
+   *     return token.aud ? 'jwt' : 'opaque';
    *   }
    * }
    * ```
@@ -1834,9 +1827,9 @@ const DEFAULTS = {
   /*
    * audiences
    *
-   * description: Helper used by the OP to push additional audiences to issued Access and
-   *   ClientCredentials Tokens. The return value should either be falsy to omit adding additional
-   *   audiences or an array of strings to push.
+   * description: Helper used by the OP to set an audience to issued Access Tokens. The return value
+   *   should either be falsy use the default audience (client) or an array of string aud values,
+   *   or a single string aud value.
    */
   async audiences(ctx, sub, token, use) { // eslint-disable-line no-unused-vars
     // @param ctx   - koa request context

lib/helpers/ensure_conform.js

@@ -1,12 +1,20 @@
 const assert = require('assert');
 
-module.exports = function ensureConform(audiences) {
-  assert(Array.isArray(audiences) && audiences.length, 'audiences must be an array with members');
+module.exports = function ensureConform(audience) {
+  assert(
+    (Array.isArray(audience) || typeof audience === 'string') && audience.length,
+    'audiences must be an array with members or a single string value',
+  );
 
-  const value = audiences.slice();
-  value.forEach((audience) => {
-    assert(audience && typeof audience === 'string', 'audiences must be non-empty string values');
-  });
+  let value;
+  if (typeof audience === 'string') {
+    value = audience;
+  } else {
+    value = [...audience];
+    value.forEach((aud) => {
+      assert(typeof aud === 'string' && aud.length, 'audiences must be non-empty string values');
+    });
+  }
 
   return value;
 };

test/resource_indicators/resource_indicators.config.js

@@ -52,7 +52,7 @@ config.audiences = ({ oidc: { params, route, entities } }, sub, token, use) => {
       }
     });
 
-    return resources;
+    return resources.length === 1 ? resources[0] : resources;
   }
 
   return undefined;