@adobe/spacecat-shared-http-utils 1.6.7 → 1.6.9

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-http-utils-v1.6.9](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-http-utils-v1.6.8...@adobe/spacecat-shared-http-utils-v1.6.9) (2024-09-14)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#369](https://github.com/adobe/spacecat-shared/issues/369)) ([5412d7b](https://github.com/adobe/spacecat-shared/commit/5412d7be554b9940d43b39b18f2913146e866846))
+
+# [@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)
 
 

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.7",
+  "version": "1.6.9",
   "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": {
@@ -32,12 +36,12 @@
     "@adobe/fetch": "4.1.8",
     "@adobe/spacecat-shared-utils": "1.19.1",
     "@adobe/spacecat-shared-data-access": "1.41.3",
-    "jose": "5.7.0"
+    "jose": "5.9.2"
   },
   "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"
+    "sinon": "18.0.1"
   }
 }

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 });
     }