@adobe/spacecat-shared-http-utils 1.6.6 → 1.6.8

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-http-utils-v1.6.8](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-http-utils-v1.6.7...@adobe/spacecat-shared-http-utils-v1.6.8) (2024-08-22)
+
+
+### Bug Fixes
+
+* add Scoped API Key docs ([#342](https://github.com/adobe/spacecat-shared/issues/342)) ([2fbf707](https://github.com/adobe/spacecat-shared/commit/2fbf707dfeff914dc47ae1f9860629873927e03e))
+
+# [@adobe/spacecat-shared-http-utils-v1.6.7](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-http-utils-v1.6.6...@adobe/spacecat-shared-http-utils-v1.6.7) (2024-08-19)
+
+
+### Bug Fixes
+
+* add try-catch block to authentication manager ([#336](https://github.com/adobe/spacecat-shared/issues/336)) ([a6cf629](https://github.com/adobe/spacecat-shared/commit/a6cf6290e4b8330956fdbb80406523853b0a7b51))
+
 # [@adobe/spacecat-shared-http-utils-v1.6.6](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-http-utils-v1.6.5...@adobe/spacecat-shared-http-utils-v1.6.6) (2024-08-19)
 
 

package/README.md

@@ -1,6 +1,7 @@
-# Response Helper Functions. 
+# Spacecat Shared - HTTP Utilities 
 
-A set of TypeScript functions for creating HTTP responses with standardized formats.
+A set of TypeScript functions for creating HTTP responses with standardized formats, and classes for dealing with
+authenticating HTTP requests.
 
 ## Table of Contents
 
@@ -76,6 +77,72 @@ Creates a response for a not found scenario with an error message and optional h
 
 Creates a response for an internal server error with an error message and optional headers.
 
+## Authentication
+
+This package includes classes for dealing with authenticating HTTP requests.
+
+### ScopedApiKeyHandler
+
+Scoped API keys are defined in the datalayer and can be used to authenticate requests to the Spacecat API. They employ
+"scopes" to enable fine-grained access to resources. An example API key entity looks like this (`id` omitted):
+
+```
+{
+  "name": "Example API Key",
+  "hashedApiKey": "4c806362b613f7496abf284146efd31da90e4b16169fe001841ca17290f427c4",
+  "createdAt": "2024-08-21T19:00:00.000Z",
+  "expiresAt": "2024-12-21T19:00:00.000Z",
+  "scopes": [
+    { "name": "imports.write" },
+    { "name": "imports.read" }
+  ]
+}
+```
+
+Key points on the above:
+- `hashedApiKey` is the SHA-256 hash of the actual API key ("test-api-key" above)
+- `scopes` are the permissions granted to the API key
+- Each `scope` object can contain additional data, but the `name` field is required
+
+The `ScopedApiKeyHandler` class is used to authenticate requests using scoped API keys. To support the existing 
+Legacy API keys, it should be ordered after the `LegacyApiKeyHandler` in the `authHandlers` array. This enables requests
+with the existing API keys to be authenticated quickly without requiring a database lookup.
+
+#### Checking for scope access
+
+To enable a new scope, first refer to the `scopeNames` array in the ApiKey model (/packages/spacecat-shared-data-access/src/models/api-key.js).
+If the scope you need is not listed here, please add it. Note the convention for scope names is `resource.action`, 
+e.g. `imports.write` or `sites.read_all`. The `_all` action suffix indicates access beyond resources created (or
+jobs initiated by) the current API key.
+
+Next, you will want to check that the API used to make the request has access to the required scope(s) from your
+controller. The `authWrapper` adds an `auth` helper to the context which makes this easy. Here's an example of how to 
+check for scope access from a controller:
+
+```
+// This route requires the 'imports.write' scope
+function protectedRoute(context) {
+  const { auth } = context;
+  
+  try {
+    auth.checkScopes(['imports.write']);
+  } catch (error) {
+    throw new ErrorWithStatusCode('Missing required scopes', 401);
+  }
+  
+  return ok('You have access to this resource');
+}
+```
+
+Need additional details from the API key entity object? The `authWrapper` places the authenticated `authInfo` object
+into the context at `context.attributes.authInfo`, with the API key entity available in its `profile` property.
+
+#### Creating a new API key
+
+This is currently a manual process, and involves duplicating an existing API key entity in the datalayer and updating
+its properties. For the table to update, refer to the `TABLE_NAME_API_KEYS` constant (which will be overridden on prod).
+
+In the future we are planning to support a way for clients to request their own API key, given a valid IMS token.
 
 ## Contributing
 

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@adobe/spacecat-shared-http-utils",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "description": "Shared modules of the Spacecat Services - HTTP Utils",
   "type": "module",
+  "engines": {
+    "node": "^20.0.0 <21.0.0",
+    "npm": "^10.0.0 <11.0.0"
+  },
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "scripts": {
@@ -36,7 +40,7 @@
   },
   "devDependencies": {
     "@adobe/helix-shared-wrap": "2.0.2",
-    "chai": "4.5.0",
+    "chai": "5.1.1",
     "chai-as-promised": "8.0.0",
     "sinon": "18.0.0"
   }

package/src/auth/auth-wrapper.js

@@ -54,7 +54,7 @@ export function authWrapper(fn, opts = {}) {
           checkScopes: (scopes) => checkScopes(scopes, authInfo, log),
         };
       }
-    } catch (error) {
+    } catch {
       return new Response('Unauthorized', { status: 401 });
     }
 

package/src/auth/authentication-manager.js

@@ -45,8 +45,13 @@ export default class AuthenticationManager {
     for (const handler of this.handlers) {
       this.log.debug(`Trying to authenticate with ${handler.name}`);
 
-      // eslint-disable-next-line no-await-in-loop
-      const authInfo = await handler.checkAuth(request, context);
+      let authInfo;
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        authInfo = await handler.checkAuth(request, context);
+      } catch (error) {
+        this.log.error(`Failed to authenticate with ${handler.name}:`, error);
+      }
 
       if (isObject(authInfo)) {
         this.log.info(`Authenticated with ${handler.name}`);

package/src/auth/handlers/scoped-api-key.js

@@ -29,17 +29,14 @@ export default class ScopedApiKeyHandler extends AbstractHandler {
     if (!dataAccess) {
       throw new Error('Data access is required');
     }
-    this.log('Checking for API key in the request headers', 'debug');
 
     const apiKeyFromHeader = headers['x-api-key'];
     if (!hasText(apiKeyFromHeader)) {
       return null;
     }
 
-    this.log(`Checking for API key: ${apiKeyFromHeader}`, 'debug');
     // Keys are stored by their hash, so we need to hash the key to look it up
     const hashedApiKey = hashWithSHA256(apiKeyFromHeader);
-    this.log(`Checking for API key with hash: ${hashedApiKey}`, 'debug');
     const apiKeyEntity = await dataAccess.getApiKeyByHashedApiKey(hashedApiKey);
 
     if (!apiKeyEntity) {
@@ -52,7 +49,6 @@ export default class ScopedApiKeyHandler extends AbstractHandler {
     const authInfo = new AuthInfo()
       .withProfile(apiKeyEntity) // Include the API key entity as the profile
       .withType(this.name);
-    this.log('Successfully constructed authInfo object', 'debug');
 
     // Verify that the api key has not expired or been revoked
     const now = new Date().toISOString();