@adobe/spacecat-shared-http-utils 1.3.5 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-http-utils-v1.5.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-http-utils-v1.4.0...@adobe/spacecat-shared-http-utils-v1.5.0) (2024-08-09)
+
+
+### Features
+
+* Introduce scoped API keys ([#312](https://github.com/adobe/spacecat-shared/issues/312)) ([449d273](https://github.com/adobe/spacecat-shared/commit/449d2736154d7e92fb4a3d1f9f290e15e665aa5e))
+
+# [@adobe/spacecat-shared-http-utils-v1.4.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-http-utils-v1.3.5...@adobe/spacecat-shared-http-utils-v1.4.0) (2024-07-30)
+
+
+### Features
+
+* move auth wrappers from api-service ([#307](https://github.com/adobe/spacecat-shared/issues/307)) ([3094a99](https://github.com/adobe/spacecat-shared/commit/3094a999f330dbe007b64fbfc3f282bd56807b37))
+
 # [@adobe/spacecat-shared-http-utils-v1.3.5](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-http-utils-v1.3.4...@adobe/spacecat-shared-http-utils-v1.3.5) (2024-07-27)
 
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@adobe/spacecat-shared-http-utils",
-  "version": "1.3.5",
+  "version": "1.5.0",
   "description": "Shared modules of the Spacecat Services - HTTP Utils",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "scripts": {
-    "test": "c8 mocha",
+    "test": "c8 mocha --spec=test/**/*.test.js",
     "lint": "eslint .",
     "clean": "rm -rf package-lock.json node_modules"
   },
@@ -29,9 +29,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@adobe/fetch": "4.1.8"
+    "@adobe/fetch": "4.1.8",
+    "@adobe/spacecat-shared-utils": "1.19.1",
+    "@adobe/spacecat-shared-data-access": "1.39.0",
+    "jose": "5.6.3"
   },
   "devDependencies": {
-    "chai": "4.5.0"
+    "@adobe/helix-shared-wrap": "2.0.2",
+    "chai": "4.5.0",
+    "chai-as-promised": "8.0.0",
+    "sinon": "18.0.0"
   }
 }

package/src/auth/auth-info.js

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * The auth info class represents information about the current authentication state.
+ */
+export default class AuthInfo {
+  constructor() {
+    Object.assign(this, {
+      authenticated: false,
+      profile: null,
+      scopes: [],
+    });
+  }
+
+  /**
+   * Set the authenticated flag.
+   * @param {boolean} value - The value of the authenticated flag
+   * @returns {AuthInfo} The auth info object
+   */
+  withAuthenticated(value) {
+    this.authenticated = value;
+    return this;
+  }
+
+  /**
+   * Set the profile. A profile is an object that contains information about the user.
+   * @param {Object} profile - The user profile
+   * @return {AuthInfo} The auth info object
+   */
+  withProfile(profile) {
+    this.profile = profile;
+    return this;
+  }
+
+  /**
+   * Set the type of the authentication that was performed.
+   * @param {string} value - The type of the authentication
+   * @return {AuthInfo} The auth info object
+   */
+  withType(value) {
+    this.type = value;
+    return this;
+  }
+
+  /**
+   * Set the reason that authentication has failed.
+   * @param {string} reason - The reason for auth failure
+   * @return {AuthInfo} The auth info object
+   */
+  withReason(reason) {
+    this.reason = reason;
+    return this;
+  }
+
+  /**
+   * Set the scopes that this auth info instance has access to.
+   * @param {Array<{name: string, domains?: Array<string>}>} scopes - The array of scope objects
+   * @return {AuthInfo} The auth info object
+   */
+  withScopes(scopes) {
+    this.scopes = scopes;
+    return this;
+  }
+
+  getScopes() { return this.scopes; }
+
+  getProfile() { return this.profile; }
+
+  getReason() { return this.reason; }
+
+  isAuthenticated() { return this.authenticated; }
+}

package/src/auth/auth-wrapper.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2023 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { Response } from '@adobe/fetch';
+
+import { isObject } from '@adobe/spacecat-shared-utils';
+import AuthenticationManager from './authentication-manager.js';
+import { checkScopes } from './check-scopes.js';
+
+const ANONYMOUS_ENDPOINTS = [
+  'GET /slack/events',
+  'POST /slack/events',
+];
+
+export function authWrapper(fn, opts = {}) {
+  let authenticationManager;
+
+  return async (request, context) => {
+    const { log, pathInfo: { method, suffix } } = context;
+
+    const route = `${method.toUpperCase()} ${suffix}`;
+
+    if (ANONYMOUS_ENDPOINTS.includes(route)
+        || route.startsWith('POST /hooks/site-detection/')
+        || method.toUpperCase() === 'OPTIONS') {
+      return fn(request, context);
+    }
+
+    if (!authenticationManager) {
+      if (!Array.isArray(opts.authHandlers)) {
+        log.error('Invalid auth handlers');
+        return new Response('Server error', { status: 500 });
+      }
+
+      authenticationManager = AuthenticationManager.create(opts.authHandlers, log);
+    }
+
+    try {
+      const authInfo = await authenticationManager.authenticate(request, context);
+
+      // Add a helper function to the context for checking scoped API keys.
+      // authInfo is available at context.attributes.authInfo.
+      if (!isObject(context.auth)) {
+        context.auth = {
+          checkScopes: (scopes) => checkScopes(scopes, authInfo, log),
+        };
+      }
+    } catch (error) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+
+    return fn(request, context);
+  };
+}

package/src/auth/authentication-manager.js

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { isObject } from '@adobe/spacecat-shared-utils';
+
+import NotAuthenticatedError from './errors/not-authenticated.js';
+
+/**
+ * Authentication manager. It will try to authenticate the request with all the provided handlers.
+ * If none of the handlers are able to authenticate the request, it will throw
+ * a NotAuthenticatedError.
+ * @class
+ */
+export default class AuthenticationManager {
+  constructor(log) {
+    this.log = log;
+    this.handlers = [];
+  }
+
+  /**
+   * Register a handler. This method is private and should not be called directly.
+   * The handlers are used in the order they are registered.
+   * @param {AbstractHandler} Handler - The handler to be registered
+   */
+  #registerHandler(Handler) {
+    this.handlers.push(new Handler(this.log));
+  }
+
+  /**
+   * Authenticate the request with all the handlers.
+   * @param {Object} request - The request object
+   * @param {UniversalContext} context - The context object
+   * @return {Promise<AuthInfo>} The authentication info
+   * @throws {NotAuthenticatedError} If no handler was able to authenticate the request
+   */
+  async authenticate(request, context) {
+    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);
+
+      if (isObject(authInfo)) {
+        this.log.info(`Authenticated with ${handler.name}`);
+
+        context.attributes = context.attributes || {};
+        context.attributes.authInfo = authInfo;
+
+        return authInfo;
+      } else {
+        this.log.debug(`Failed to authenticate with ${handler.name}`);
+      }
+    }
+
+    this.log.info('No authentication handler was able to authenticate the request');
+    throw new NotAuthenticatedError();
+  }
+
+  /**
+   * Create an instance of AuthenticationManager.
+   * @param {Array<AbstractHandler>} handlers - The handlers to be used for authentication
+   * @param {Object} log - The logger object
+   * @return {AuthenticationManager} The authentication manager
+   */
+  static create(handlers, log) {
+    const manager = new AuthenticationManager(log);
+
+    if (!Array.isArray(handlers)) {
+      throw new Error('Invalid handlers');
+    }
+
+    if (!handlers.length) {
+      throw new Error('No handlers provided');
+    }
+
+    handlers.forEach((handler) => {
+      manager.#registerHandler(handler);
+    });
+
+    return manager;
+  }
+}

package/src/auth/check-scopes.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isObject } from '@adobe/spacecat-shared-utils';
+
+/**
+ * Check if the given AuthInfo has the requested scopes. Throws an error if any scopes are missing.
+ * @param {Array<string>} scopes - The scopes required for the request
+ * @param {AuthInfo} authInfo - Authentication state for the current request
+ * @param {Logger} log - Logger
+ */
+export function checkScopes(scopes, authInfo, log) {
+  if (!isObject(authInfo)) {
+    throw new Error('Auth info is required');
+  }
+
+  // Check that each required scope is present in authInfo
+  const missingScopes = [];
+  const authInfoScopeNames = authInfo.getScopes().map((scopeObject) => scopeObject.name);
+  scopes.forEach((scope) => {
+    if (!authInfoScopeNames.includes(scope)) {
+      missingScopes.push(scope);
+    }
+  });
+
+  if (missingScopes.length > 0) {
+    log.error(`API key with ID: ${authInfo.getProfile()?.api_key_id} does not have required scopes. It's missing: ${missingScopes.join(',')}`);
+    throw new Error(`API key is missing the [${missingScopes.join(',')}] scope(s) required for this resource`);
+  }
+
+  // Otherwise: all good
+}

package/src/auth/errors/not-authenticated.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export default class NotAuthenticatedError extends Error {
+  constructor() {
+    super('Not authenticated');
+  }
+}

package/src/auth/generate-hash.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import crypto from 'crypto';
+
+export function hashWithSHA256(input) {
+  return crypto.createHash('sha256').update(input).digest('hex');
+}

package/src/auth/handlers/abstract.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export default class AbstractHandler {
+  constructor(name, log) {
+    if (new.target === AbstractHandler) {
+      throw new TypeError('Cannot construct AbstractHandler instances directly');
+    }
+    this.name = name;
+    this.logger = log;
+  }
+
+  /**
+   * Log a message with a specific log level. Log messages are prefixed with the handler name.
+   * @param {string} message - The log message
+   * @param {string} level - The log level
+   */
+  log(message, level) {
+    this.logger[level](`[${this.name}] ${message}`);
+  }
+
+  /**
+   * Check the authentication of a request. This method must be implemented by the concrete handler.
+   * It should return an object of type AuthInfo if the request is authenticated,
+   * otherwise it should return null.
+   * @param {Object} request - The request object
+   * @param {UniversalContext} context - The context object
+   * @return {Promise<AuthInfo|null>} The authentication info
+   * or null if the request is not authenticated
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars,class-methods-use-this
+  async checkAuth(request, context) {
+    throw new Error('checkAuth method must be implemented');
+  }
+}

package/src/auth/handlers/config/ims-stg.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+export default {
+  name: 'ims-na1-stg1',
+  discoveryUrl: 'https://ims-na1-stg1.adobelogin.com/ims/.well-known/openid-configuration',
+  // todo: fetch from discovery document
+  discovery: {
+    issuer: 'https://ims-na1-stg1.adobelogin.com',
+    authorization_endpoint: 'https://ims-na1-stg1.adobelogin.com/ims/authorize/v2',
+    token_endpoint: 'https://ims-na1-stg1.adobelogin.com/ims/token/v3',
+    userinfo_endpoint: 'https://ims-na1-stg1.adobelogin.com/ims/userinfo/v2',
+    revocation_endpoint: 'https://ims-na1-stg1.adobelogin.com/ims/revoke',
+    jwks_uri: 'https://ims-na1-stg1.adobelogin.com/ims/keys',
+  },
+};

package/src/auth/handlers/config/ims.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+export default {
+  name: 'ims-na1',
+  discoveryUrl: 'https://ims-na1.adobelogin.com/ims/.well-known/openid-configuration',
+  discovery: {
+    issuer: 'https://ims-na1.adobelogin.com',
+    authorization_endpoint: 'https://ims-na1.adobelogin.com/ims/authorize/v2',
+    token_endpoint: 'https://ims-na1.adobelogin.com/ims/token/v3',
+    userinfo_endpoint: 'https://ims-na1.adobelogin.com/ims/userinfo/v2',
+    revocation_endpoint: 'https://ims-na1.adobelogin.com/ims/revoke',
+    jwks_uri: 'https://ims-na1.adobelogin.com/ims/keys',
+  },
+};

package/src/auth/handlers/ims.js

@@ -0,0 +1,138 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+import {
+  createLocalJWKSet,
+  createRemoteJWKSet,
+  decodeJwt,
+  jwtVerify,
+} from 'jose';
+
+import configProd from './config/ims.js';
+import configDev from './config/ims-stg.js';
+
+import AbstractHandler from './abstract.js';
+import AuthInfo from '../auth-info.js';
+
+const IGNORED_PROFILE_PROPS = [
+  'id',
+  'type',
+  'as_id',
+  'ctp',
+  'pac',
+  'rtid',
+  'moi',
+  'rtea',
+  'user_id',
+  'fg',
+  'aa_id',
+];
+
+const loadConfig = (context) => {
+  const funcVersion = context.func?.version;
+  const isDev = /^ci\d*$/i.test(funcVersion);
+  context.log.debug(`Function version: ${funcVersion} (isDev: ${isDev})`);
+  /* c8 ignore next */
+  return isDev ? configDev : configProd;
+};
+
+const getBearerToken = (context) => {
+  const authorizationHeader = context.pathInfo?.headers?.authorization || '';
+
+  if (!authorizationHeader.startsWith('Bearer ')) {
+    return null;
+  }
+
+  return authorizationHeader.replace('Bearer ', '');
+};
+
+const transformProfile = (payload) => {
+  const profile = { ...payload };
+
+  profile.email = payload.user_id;
+  IGNORED_PROFILE_PROPS.forEach((prop) => delete profile[prop]);
+
+  return profile;
+};
+
+export default class AdobeImsHandler extends AbstractHandler {
+  constructor(log) {
+    super('ims', log);
+    this.jwksCache = null;
+  }
+
+  async #getJwksUri(config) {
+    if (!this.jwksCache) {
+      /* c8 ignore next 3 */
+      this.jwksCache = config.discovery.jwks
+        ? createLocalJWKSet(config.discovery.jwks)
+        : createRemoteJWKSet(new URL(config.discovery.jwks_uri));
+    }
+
+    return this.jwksCache;
+  }
+
+  async #validateToken(token, config) {
+    const decoded = await decodeJwt(token);
+    if (config.name !== decoded.as) {
+      throw new Error(`Token not issued by expected idp: ${config.name} != ${decoded.as}`);
+    }
+
+    const jwks = await this.#getJwksUri(config);
+    const { payload } = await jwtVerify(token, jwks);
+
+    const now = Date.now();
+    const expiresIn = Number.parseInt(payload.expires_in, 10);
+    const createdAt = Number.parseInt(payload.created_at, 10);
+
+    if (Number.isNaN(expiresIn) || Number.isNaN(createdAt)) {
+      throw new Error('expires_in and created_at claims must be numbers');
+    }
+
+    if (createdAt >= now) {
+      throw new Error('created_at should be in the past');
+    }
+
+    const ttl = Math.floor((createdAt + expiresIn - now) / 1000);
+    if (ttl <= 0) {
+      throw new Error('token expired');
+    }
+
+    payload.ttl = ttl;
+
+    return payload;
+  }
+
+  async checkAuth(request, context) {
+    const token = getBearerToken(context);
+    if (!hasText(token)) {
+      this.log('No bearer token provided', 'debug');
+      return null;
+    }
+
+    try {
+      const config = loadConfig(context);
+      const payload = await this.#validateToken(token, config);
+      const profile = transformProfile(payload);
+
+      return new AuthInfo()
+        .withType(this.name)
+        .withAuthenticated(true)
+        .withProfile(profile);
+    } catch (e) {
+      this.log(`Failed to validate token: ${e.message}`, 'error');
+    }
+
+    return null;
+  }
+}

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

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+
+import AuthInfo from '../auth-info.js';
+import AbstractHandler from './abstract.js';
+
+const ADMIN_ENDPOINTS = [
+  'GET /trigger',
+  'POST /sites',
+  'POST /event/fulfillment',
+  'POST /slack/channels/invite-by-user-id',
+];
+
+/**
+ * Handler for legacy API key authentication. This handler is used to authenticate requests
+ * that contain a legacy API key in the `x-api-key` header.
+ */
+export default class LegacyApiKeyHandler extends AbstractHandler {
+  constructor(log) {
+    super('legacyApiKey', log);
+  }
+
+  async checkAuth(request, context) {
+    const expectedUserApiKey = context.env?.USER_API_KEY;
+    const expectedAdminApiKey = context.env?.ADMIN_API_KEY;
+
+    if (!hasText(expectedUserApiKey) || !hasText(expectedAdminApiKey)) {
+      this.log('API keys were not configured', 'error');
+      return null;
+    }
+
+    const apiKeyFromHeader = context.pathInfo?.headers['x-api-key'];
+
+    if (!hasText(apiKeyFromHeader)) {
+      return null;
+    }
+
+    const isRouteAdminOnly = ADMIN_ENDPOINTS.includes(context.pathInfo.route);
+    const isApiKeyValid = isRouteAdminOnly
+      ? apiKeyFromHeader === expectedAdminApiKey
+      : apiKeyFromHeader === expectedUserApiKey || apiKeyFromHeader === expectedAdminApiKey;
+
+    if (isApiKeyValid) {
+      const profile = isRouteAdminOnly ? { user_id: 'admin' } : { user_id: 'legacy-user' };
+      return new AuthInfo()
+        .withAuthenticated(true)
+        .withProfile(profile)
+        .withType(this.name);
+    }
+
+    return null;
+  }
+}

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

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { hasText, isIsoDate } from '@adobe/spacecat-shared-utils';
+import AbstractHandler from './abstract.js';
+import { hashWithSHA256 } from '../generate-hash.js';
+import AuthInfo from '../auth-info.js';
+
+/**
+ * Handler to support API keys which include scope details. These API keys are stored in the data
+ * layer and require context.dataAccess in order to authenticate each request.
+ */
+export default class ScopedApiKeyHandler extends AbstractHandler {
+  constructor(log) {
+    super('scopedApiKey', log);
+  }
+
+  async checkAuth(request, context) {
+    const { dataAccess, pathInfo: { headers = {} } } = context;
+    if (!dataAccess) {
+      throw new Error('Data access is required');
+    }
+
+    const apiKeyFromHeader = headers['x-api-key'];
+    if (!hasText(apiKeyFromHeader)) {
+      return null;
+    }
+
+    // Keys are stored by their hash, so we need to hash the key to look it up
+    const hashedKey = hashWithSHA256(apiKeyFromHeader);
+    const apiKeyEntity = await dataAccess.getApiKeyByHashedKey(hashedKey);
+
+    if (!apiKeyEntity) {
+      this.log(`No API key entity found in the data layer for the provided API key: ${apiKeyFromHeader}`, 'error');
+      return null;
+    }
+
+    // We have an API key entity, and need to check if it's still valid
+    const authInfo = new AuthInfo()
+      .withProfile(apiKeyEntity) // Include the API key entity as the profile
+      .withType(this.name);
+
+    // Verify that the api key has not expired or been revoked
+    const now = new Date().toISOString();
+    if (isIsoDate(apiKeyEntity.getExpiresAt()) && apiKeyEntity.getExpiresAt() < now) {
+      this.log(`API key has expired. Name: ${apiKeyEntity.getName()}, id: ${apiKeyEntity.getId()}`, 'error');
+      return authInfo.withReason('API key has expired');
+    }
+
+    if (isIsoDate(apiKeyEntity.getRevokedAt()) && apiKeyEntity.getRevokedAt() < now) {
+      this.log(`API key has been revoked. Name: ${apiKeyEntity.getName()} id: ${apiKeyEntity.getId()}`, 'error');
+      return authInfo.withReason('API key has been revoked');
+    }
+
+    // API key is valid: return auth info with scope details from the API key entity
+    return authInfo
+      .withAuthenticated(true)
+      .withScopes(apiKeyEntity.getScopes());
+  }
+}

package/src/auth/readme.md

@@ -0,0 +1,82 @@
+Sure, here's a README that provides an overview of the architecture, how to use the authentication wrapper, and how to implement an example authentication handler:
+
+---
+
+# Authentication System
+
+The authentication system is designed to secure AWS Lambda functions by integrating various authentication methods.
+It includes an authentication wrapper, a manager, and handler classes that implement specific authentication logic.
+
+## Architecture
+
+The architecture of the authentication system consists of the following components:
+
+### Authentication Wrapper
+
+The `authWrapper` function wraps your Lambda function, enforcing authentication based on defined handlers.
+It determines which endpoints require authentication and delegates the actual authentication process to the `AuthenticationManager`.
+
+### Authentication Manager
+
+The `AuthenticationManager` class manages multiple authentication handlers.
+It attempts to authenticate each request by delegating to the registered handlers in sequence.
+
+### AuthInfo Class
+
+The `AuthInfo` class represents information about the current authentication state, 
+including whether the user is authenticated, the user's profile, and the type of authentication performed.
+
+### Handlers
+
+Handlers are responsible for implementing specific authentication mechanisms. 
+Each handler extends the `AbstractHandler` class and implements the `checkAuth` method.
+
+## Getting Started
+
+### Using the Authentication Wrapper
+
+To secure your Lambda function, wrap it with the `authWrapper` function. You must provide an array of authentication handlers to the wrapper.
+
+```javascript
+import { Response } from '@adobe/fetch';
+import auth from './auth-wrapper.js';
+
+const run = async (request, context) => {
+  const authInfo = context.attributes.authInfo;
+  return new Response(`Hello, ${authInfo.profile.user_id}!`, { status: 200 });
+};
+
+export const main = wrap(run)
+  .with(auth, { authHandlers: [LegacyApiKeyHandler, AdobeImsHandler] });
+```
+
+### Implementing an Authentication Handler
+
+To implement a new authentication handler, extend the `AbstractHandler` class and implement the `checkAuth` method.
+This method should return an `AuthInfo` object if authentication is successful or `null` if it fails.
+
+```javascript
+import AbstractHandler from './abstract.js';
+import AuthInfo from '../auth-info.js';
+
+export default class ExampleHandler extends AbstractHandler {
+  constructor(log) {
+    super('exampleHandler', log);
+  }
+
+  async checkAuth(request, context) {
+    // Implement your authentication logic here
+
+    const isAuthenticated = true; // Replace with actual authentication logic
+    if (isAuthenticated) {
+      const profile = { user_id: 'example-user' };
+      return new AuthInfo()
+        .withAuthenticated(true)
+        .withProfile(profile)
+        .withType(this.name);
+    }
+
+    return null;
+  }
+}
+```

package/src/enrich-path-info-wrapper.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export function enrichPathInfo(fn) { // export for testing
+  return async (request, context) => {
+    const [, route] = context?.pathInfo?.suffix?.split(/\/+/) || [];
+    context.pathInfo = {
+      ...context.pathInfo,
+      ...{
+        method: request.method.toUpperCase(),
+        headers: request.headers.plain(),
+        route,
+      },
+    };
+    return fn(request, context);
+  };
+}

package/src/index.d.ts

@@ -24,3 +24,8 @@ export declare function notFound(message?: string, headers?: object): Response;
 export declare function internalServerError(message?: string, headers?: object): Response;
 
 export declare function found(location: string): Response;
+
+/**
+ * Utility functions
+ */
+export function hashWithSHA256(input: string): string;

package/src/index.js

@@ -12,6 +12,9 @@
 
 import { Response } from '@adobe/fetch';
 
+import LegacyApiKeyHandler from './auth/handlers/legacy-api-key.js';
+import AdobeImsHandler from './auth/handlers/ims.js';
+
 const HEADER_CONTENT_TYPE = 'content-type';
 const HEADER_ERROR = 'x-error';
 
@@ -83,3 +86,9 @@ export function internalServerError(message = 'internal server error', headers =
     ...headers,
   });
 }
+
+export { authWrapper } from './auth/auth-wrapper.js';
+export { enrichPathInfo } from './enrich-path-info-wrapper.js';
+export { hashWithSHA256 } from './auth/generate-hash.js';
+
+export { AdobeImsHandler, LegacyApiKeyHandler };