@aligent/cdk-secure-rest-api 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @aligent/cdk-secure-rest-api
+
+## 1.1.0
+
+### Minor Changes
+
+- [#1667](https://github.com/aligent/cdk-constructs/pull/1667) [`631a92c`](https://github.com/aligent/cdk-constructs/commit/631a92ce3b8846a97c757a2145a369f287ef4ad3) Thanks [@toddhainsworth](https://github.com/toddhainsworth)! - Add new `SecureRestApi` construct for provisioning an API Gateway REST API secured with API key authentication and usage plan throttling. Supports configurable routes (accepting any CDK `Integration`), CORS options, and throttle limits.
+
+### Patch Changes
+
+- [#1669](https://github.com/aligent/cdk-constructs/pull/1669) [`8006ed3`](https://github.com/aligent/cdk-constructs/commit/8006ed327661e66d9e9b91b2d3ec205594ba4c06) Thanks [@dependabot](https://github.com/apps/dependabot)! - chore(deps): bump the aws group across 1 directory with 9 updates

package/README.md

@@ -0,0 +1,166 @@
+# Aligent AWS Secure REST API
+
+## Overview
+
+![TypeScript version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/typescript?filename=packages/constructs/secure-rest-api/package.json&color=red) ![AWS CDK version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/aws-cdk?filename=packages/constructs/secure-rest-api/package.json) ![NPM version](https://img.shields.io/npm/v/%40aligent%2Fcdk-secure-rest-api?color=green)
+
+A CDK construct for provisioning an API Gateway REST API secured with API Key authentication and usage plan throttling. Routes accept any CDK `Integration`, giving callers full control over how endpoints are wired.
+
+## Features
+
+- API Gateway REST API with API Key authentication (`apiKeyRequired: true` on all routes)
+- Usage plan with configurable throttle rate and burst limits
+- Configurable CORS preflight options
+- Accepts any CDK `Integration` per route (Lambda, HTTP, Mock, Step Functions, etc.)
+
+## Installation
+
+```bash
+npm install @aligent/cdk-secure-rest-api
+```
+
+Or with yarn:
+
+```bash
+yarn add @aligent/cdk-secure-rest-api aws-cdk-lib constructs
+```
+
+### Peer Dependencies
+
+- `aws-cdk-lib` (^2.113.0)
+- `constructs` (^10.5.0)
+
+## Basic Usage
+
+```typescript
+import { SecureRestApi } from '@aligent/cdk-secure-rest-api';
+import { LambdaIntegration } from 'aws-cdk-lib/aws-apigateway';
+import { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+
+const api = new SecureRestApi(this, 'Api', {
+  apiName: 'my-api',
+  routes: [
+    {
+      path: 'items',
+      methods: [HttpMethod.GET],
+      integration: new LambdaIntegration(myFunction),
+    },
+  ],
+});
+
+// Access created resources
+const { api, apiKey, usagePlan } = api;
+```
+
+## Configuration Examples
+
+### Multiple routes and methods
+
+```typescript
+const api = new SecureRestApi(this, 'Api', {
+  apiName: 'my-api',
+  routes: [
+    {
+      path: 'items',
+      methods: [HttpMethod.GET, HttpMethod.POST],
+      integration: new LambdaIntegration(itemsFunction),
+    },
+    {
+      path: 'orders',
+      methods: [HttpMethod.GET],
+      integration: new LambdaIntegration(ordersFunction),
+    },
+  ],
+});
+```
+
+### Custom throttling
+
+```typescript
+const api = new SecureRestApi(this, 'Api', {
+  apiName: 'my-api',
+  throttle: {
+    rateLimit: 50,   // requests per second
+    burstLimit: 100,
+  },
+  routes: [...],
+});
+```
+
+### Custom CORS configuration
+
+```typescript
+const api = new SecureRestApi(this, 'Api', {
+  apiName: 'my-api',
+  corsOptions: {
+    allowOrigins: ['https://example.com'],  // overrides default (all origins)
+    additionalMethods: ['POST'],            // appended to GET, OPTIONS
+    additionalHeaders: ['Authorization'],   // appended to Content-Type, X-Api-Key
+  },
+  routes: [...],
+});
+```
+
+## Configuration Reference
+
+### `apiName` (string) — required
+
+The name of the REST API and the base for generated resource names.
+
+### `description` (string)
+
+Description for the API Gateway REST API.
+
+Default: `REST API for {apiName} service`
+
+### `routes` (SecureRestApiRoute[]) — required
+
+Routes to register on the API. Each route requires:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` | The resource path (leading slash is stripped automatically) |
+| `methods` | `HttpMethod[]` | HTTP methods to register on the resource |
+| `integration` | `Integration` | Any CDK API Gateway integration |
+
+### `throttle` (object)
+
+Throttling limits applied to the usage plan.
+
+| Property | Type | Default |
+|----------|------|---------|
+| `rateLimit` | `number` | `100` |
+| `burstLimit` | `number` | `200` |
+
+### `corsOptions` (object)
+
+CORS preflight configuration applied to all resources.
+
+| Property | Type | Behaviour |
+|----------|------|-----------|
+| `allowOrigins` | `string[]` | Overrides the default (all origins) |
+| `additionalMethods` | `string[]` | Appended to the defaults: `GET`, `OPTIONS` |
+| `additionalHeaders` | `string[]` | Appended to the defaults: `Content-Type`, `X-Api-Key` |
+
+### `apiKeyName` (string)
+
+Override the name of the generated API key.
+
+Default: `{apiName}-api-key`
+
+### `usagePlanName` (string)
+
+Override the name of the generated usage plan.
+
+Default: `{apiName}-usage-plan`
+
+## Local Development
+
+[NPM link](https://docs.npmjs.com/cli/v7/commands/npm-link) can be used to develop the module locally:
+
+1. Pull this repository locally
+2. `cd` into this repository
+3. Run `npm link`
+4. `cd` into the downstream repo and run `npm link '@aligent/cdk-secure-rest-api'`
+
+The downstream repository should now include a symlink to this module, allowing local changes to be tested before pushing.

package/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecureRestApi = void 0;
+const secure_rest_api_1 = require("./lib/secure-rest-api");
+Object.defineProperty(exports, "SecureRestApi", { enumerable: true, get: function () { return secure_rest_api_1.SecureRestApi; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJpbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSwyREFJK0I7QUFFdEIsOEZBTFAsK0JBQWEsT0FLTyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7XG4gIFNlY3VyZVJlc3RBcGksXG4gIFNlY3VyZVJlc3RBcGlQcm9wcyxcbiAgU2VjdXJlUmVzdEFwaVJvdXRlLFxufSBmcm9tIFwiLi9saWIvc2VjdXJlLXJlc3QtYXBpXCI7XG5cbmV4cG9ydCB7IFNlY3VyZVJlc3RBcGksIFNlY3VyZVJlc3RBcGlQcm9wcywgU2VjdXJlUmVzdEFwaVJvdXRlIH07XG4iXX0=

package/index.ts

@@ -0,0 +1,7 @@
+import {
+  SecureRestApi,
+  SecureRestApiProps,
+  SecureRestApiRoute,
+} from "./lib/secure-rest-api";
+
+export { SecureRestApi, SecureRestApiProps, SecureRestApiRoute };

package/jest.config.ts

@@ -0,0 +1,11 @@
+/* eslint-disable */
+export default {
+  displayName: "secure-rest-api",
+  preset: "../../../jest.preset.js",
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.[tj]s$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.spec.json" }],
+  },
+  moduleFileExtensions: ["ts", "js", "html"],
+  coverageDirectory: "../../../coverage/packages/secure-rest-api",
+};

package/lib/secure-rest-api.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecureRestApi = void 0;
+const aws_apigateway_1 = require("aws-cdk-lib/aws-apigateway");
+const constructs_1 = require("constructs");
+class SecureRestApi extends constructs_1.Construct {
+    constructor(scope, id, props) {
+        var _a, _b, _c;
+        super(scope, id);
+        const { apiName, description, corsOptions, routes, throttle = { rateLimit: 100, burstLimit: 200 }, apiKeyName, usagePlanName, } = props;
+        this.api = new aws_apigateway_1.RestApi(this, "Api", {
+            restApiName: apiName,
+            description: description !== null && description !== void 0 ? description : `REST API for ${apiName} service`,
+            defaultCorsPreflightOptions: {
+                allowOrigins: (_a = corsOptions === null || corsOptions === void 0 ? void 0 : corsOptions.allowOrigins) !== null && _a !== void 0 ? _a : aws_apigateway_1.Cors.ALL_ORIGINS,
+                allowMethods: [
+                    "GET",
+                    "OPTIONS",
+                    ...((_b = corsOptions === null || corsOptions === void 0 ? void 0 : corsOptions.additionalMethods) !== null && _b !== void 0 ? _b : []),
+                ],
+                allowHeaders: [
+                    "Content-Type",
+                    "X-Api-Key",
+                    ...((_c = corsOptions === null || corsOptions === void 0 ? void 0 : corsOptions.additionalHeaders) !== null && _c !== void 0 ? _c : []),
+                ],
+            },
+        });
+        for (const route of routes) {
+            const resource = this.api.root.addResource(route.path.replace(/^\//, ""));
+            for (const method of route.methods) {
+                resource.addMethod(method, route.integration, { apiKeyRequired: true });
+            }
+        }
+        this.apiKey = new aws_apigateway_1.ApiKey(this, "ApiKey", {
+            description: `API Key for ${apiName} service`,
+            apiKeyName: apiKeyName !== null && apiKeyName !== void 0 ? apiKeyName : `${apiName}-api-key`,
+        });
+        this.usagePlan = new aws_apigateway_1.UsagePlan(this, "UsagePlan", {
+            name: usagePlanName !== null && usagePlanName !== void 0 ? usagePlanName : `${apiName}-usage-plan`,
+            description: `Usage plan for ${apiName} service`,
+            throttle,
+        });
+        this.usagePlan.addApiStage({
+            api: this.api,
+            stage: this.api.deploymentStage,
+        });
+        this.usagePlan.addApiKey(this.apiKey);
+    }
+}
+exports.SecureRestApi = SecureRestApi;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VjdXJlLXJlc3QtYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsic2VjdXJlLXJlc3QtYXBpLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLCtEQU9vQztBQUVwQywyQ0FBdUM7QUEyRHZDLE1BQWEsYUFBYyxTQUFRLHNCQUFTO0lBSzFDLFlBQVksS0FBZ0IsRUFBRSxFQUFVLEVBQUUsS0FBeUI7O1FBQ2pFLEtBQUssQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDLENBQUM7UUFFakIsTUFBTSxFQUNKLE9BQU8sRUFDUCxXQUFXLEVBQ1gsV0FBVyxFQUNYLE1BQU0sRUFDTixRQUFRLEdBQUcsRUFBRSxTQUFTLEVBQUUsR0FBRyxFQUFFLFVBQVUsRUFBRSxHQUFHLEVBQUUsRUFDOUMsVUFBVSxFQUNWLGFBQWEsR0FDZCxHQUFHLEtBQUssQ0FBQztRQUVWLElBQUksQ0FBQyxHQUFHLEdBQUcsSUFBSSx3QkFBTyxDQUFDLElBQUksRUFBRSxLQUFLLEVBQUU7WUFDbEMsV0FBVyxFQUFFLE9BQU87WUFDcEIsV0FBVyxFQUFFLFdBQVcsYUFBWCxXQUFXLGNBQVgsV0FBVyxHQUFJLGdCQUFnQixPQUFPLFVBQVU7WUFDN0QsMkJBQTJCLEVBQUU7Z0JBQzNCLFlBQVksRUFBRSxNQUFBLFdBQVcsYUFBWCxXQUFXLHVCQUFYLFdBQVcsQ0FBRSxZQUFZLG1DQUFJLHFCQUFJLENBQUMsV0FBVztnQkFDM0QsWUFBWSxFQUFFO29CQUNaLEtBQUs7b0JBQ0wsU0FBUztvQkFDVCxHQUFHLENBQUMsTUFBQSxXQUFXLGFBQVgsV0FBVyx1QkFBWCxXQUFXLENBQUUsaUJBQWlCLG1DQUFJLEVBQUUsQ0FBQztpQkFDMUM7Z0JBQ0QsWUFBWSxFQUFFO29CQUNaLGNBQWM7b0JBQ2QsV0FBVztvQkFDWCxHQUFHLENBQUMsTUFBQSxXQUFXLGFBQVgsV0FBVyx1QkFBWCxXQUFXLENBQUUsaUJBQWlCLG1DQUFJLEVBQUUsQ0FBQztpQkFDMUM7YUFDRjtTQUNGLENBQUMsQ0FBQztRQUVILEtBQUssTUFBTSxLQUFLLElBQUksTUFBTSxFQUFFLENBQUM7WUFDM0IsTUFBTSxRQUFRLEdBQUcsSUFBSSxDQUFDLEdBQUcsQ0FBQyxJQUFJLENBQUMsV0FBVyxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDO1lBQzFFLEtBQUssTUFBTSxNQUFNLElBQUksS0FBSyxDQUFDLE9BQU8sRUFBRSxDQUFDO2dCQUNuQyxRQUFRLENBQUMsU0FBUyxDQUFDLE1BQU0sRUFBRSxLQUFLLENBQUMsV0FBVyxFQUFFLEVBQUUsY0FBYyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7WUFDMUUsQ0FBQztRQUNILENBQUM7UUFFRCxJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksdUJBQU0sQ0FBQyxJQUFJLEVBQUUsUUFBUSxFQUFFO1lBQ3ZDLFdBQVcsRUFBRSxlQUFlLE9BQU8sVUFBVTtZQUM3QyxVQUFVLEVBQUUsVUFBVSxhQUFWLFVBQVUsY0FBVixVQUFVLEdBQUksR0FBRyxPQUFPLFVBQVU7U0FDL0MsQ0FBQyxDQUFDO1FBRUgsSUFBSSxDQUFDLFNBQVMsR0FBRyxJQUFJLDBCQUFTLENBQUMsSUFBSSxFQUFFLFdBQVcsRUFBRTtZQUNoRCxJQUFJLEVBQUUsYUFBYSxhQUFiLGFBQWEsY0FBYixhQUFhLEdBQUksR0FBRyxPQUFPLGFBQWE7WUFDOUMsV0FBVyxFQUFFLGtCQUFrQixPQUFPLFVBQVU7WUFDaEQsUUFBUTtTQUNULENBQUMsQ0FBQztRQUVILElBQUksQ0FBQyxTQUFTLENBQUMsV0FBVyxDQUFDO1lBQ3pCLEdBQUcsRUFBRSxJQUFJLENBQUMsR0FBZTtZQUN6QixLQUFLLEVBQUUsSUFBSSxDQUFDLEdBQUcsQ0FBQyxlQUFlO1NBQ2hDLENBQUMsQ0FBQztRQUNILElBQUksQ0FBQyxTQUFTLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUN4QyxDQUFDO0NBQ0Y7QUE1REQsc0NBNERDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHtcbiAgQXBpS2V5LFxuICBDb3JzLFxuICBJbnRlZ3JhdGlvbixcbiAgSVJlc3RBcGksXG4gIFJlc3RBcGksXG4gIFVzYWdlUGxhbixcbn0gZnJvbSBcImF3cy1jZGstbGliL2F3cy1hcGlnYXRld2F5XCI7XG5pbXBvcnQgeyBIdHRwTWV0aG9kIH0gZnJvbSBcImF3cy1jZGstbGliL2F3cy1hcGlnYXRld2F5djJcIjtcbmltcG9ydCB7IENvbnN0cnVjdCB9IGZyb20gXCJjb25zdHJ1Y3RzXCI7XG5cbmV4cG9ydCBpbnRlcmZhY2UgU2VjdXJlUmVzdEFwaVJvdXRlIHtcbiAgcGF0aDogc3RyaW5nO1xuICBtZXRob2RzOiBIdHRwTWV0aG9kW107XG4gIGludGVncmF0aW9uOiBJbnRlZ3JhdGlvbjtcbn1cblxuZXhwb3J0IGludGVyZmFjZSBTZWN1cmVSZXN0QXBpUHJvcHMge1xuICAvKipcbiAgICogVGhlIG5hbWUgb2YgdGhlIEFQSS5cbiAgICovXG4gIGFwaU5hbWU6IHN0cmluZztcblxuICAvKipcbiAgICogRGVzY3JpcHRpb24gZm9yIHRoZSBBUEkuXG4gICAqL1xuICBkZXNjcmlwdGlvbj86IHN0cmluZztcblxuICAvKipcbiAgICogQ09SUyBjb25maWd1cmF0aW9uLlxuICAgKlxuICAgKiBgYWxsb3dPcmlnaW5zYCBvdmVycmlkZXMgdGhlIGRlZmF1bHQgKGFsbCBvcmlnaW5zKS5cbiAgICogYGFkZGl0aW9uYWxNZXRob2RzYCBhbmQgYGFkZGl0aW9uYWxIZWFkZXJzYCBhcmUgYXBwZW5kZWQgdG8gdGhlIGRlZmF1bHRzXG4gICAqIChHRVQvT1BUSU9OUyBhbmQgQ29udGVudC1UeXBlL1gtQXBpLUtleSByZXNwZWN0aXZlbHkpLlxuICAgKi9cbiAgY29yc09wdGlvbnM/OiB7XG4gICAgYWxsb3dPcmlnaW5zPzogc3RyaW5nW107XG4gICAgYWRkaXRpb25hbE1ldGhvZHM/OiBzdHJpbmdbXTtcbiAgICBhZGRpdGlvbmFsSGVhZGVycz86IHN0cmluZ1tdO1xuICB9O1xuXG4gIC8qKlxuICAgKiBSb3V0ZXMgdG8gcmVnaXN0ZXIgb24gdGhlIEFQSS5cbiAgICovXG4gIHJvdXRlczogU2VjdXJlUmVzdEFwaVJvdXRlW107XG5cbiAgLyoqXG4gICAqIFRocm90dGxpbmcgbGltaXRzIGZvciB0aGUgdXNhZ2UgcGxhbi5cbiAgICogQGRlZmF1bHQgeyByYXRlTGltaXQ6IDEwMCwgYnVyc3RMaW1pdDogMjAwIH1cbiAgICovXG4gIHRocm90dGxlPzoge1xuICAgIHJhdGVMaW1pdDogbnVtYmVyO1xuICAgIGJ1cnN0TGltaXQ6IG51bWJlcjtcbiAgfTtcblxuICAvKipcbiAgICogT3ZlcnJpZGUgdGhlIGdlbmVyYXRlZCBBUEkga2V5IG5hbWUuXG4gICAqIEBkZWZhdWx0IGB7YXBpTmFtZX0tYXBpLWtleWBcbiAgICovXG4gIGFwaUtleU5hbWU/OiBzdHJpbmc7XG5cbiAgLyoqXG4gICAqIE92ZXJyaWRlIHRoZSBnZW5lcmF0ZWQgdXNhZ2UgcGxhbiBuYW1lLlxuICAgKiBAZGVmYXVsdCBge2FwaU5hbWV9LXVzYWdlLXBsYW5gXG4gICAqL1xuICB1c2FnZVBsYW5OYW1lPzogc3RyaW5nO1xufVxuXG5leHBvcnQgY2xhc3MgU2VjdXJlUmVzdEFwaSBleHRlbmRzIENvbnN0cnVjdCB7XG4gIHB1YmxpYyByZWFkb25seSBhcGk6IFJlc3RBcGk7XG4gIHB1YmxpYyByZWFkb25seSBhcGlLZXk6IEFwaUtleTtcbiAgcHVibGljIHJlYWRvbmx5IHVzYWdlUGxhbjogVXNhZ2VQbGFuO1xuXG4gIGNvbnN0cnVjdG9yKHNjb3BlOiBDb25zdHJ1Y3QsIGlkOiBzdHJpbmcsIHByb3BzOiBTZWN1cmVSZXN0QXBpUHJvcHMpIHtcbiAgICBzdXBlcihzY29wZSwgaWQpO1xuXG4gICAgY29uc3Qge1xuICAgICAgYXBpTmFtZSxcbiAgICAgIGRlc2NyaXB0aW9uLFxuICAgICAgY29yc09wdGlvbnMsXG4gICAgICByb3V0ZXMsXG4gICAgICB0aHJvdHRsZSA9IHsgcmF0ZUxpbWl0OiAxMDAsIGJ1cnN0TGltaXQ6IDIwMCB9LFxuICAgICAgYXBpS2V5TmFtZSxcbiAgICAgIHVzYWdlUGxhbk5hbWUsXG4gICAgfSA9IHByb3BzO1xuXG4gICAgdGhpcy5hcGkgPSBuZXcgUmVzdEFwaSh0aGlzLCBcIkFwaVwiLCB7XG4gICAgICByZXN0QXBpTmFtZTogYXBpTmFtZSxcbiAgICAgIGRlc2NyaXB0aW9uOiBkZXNjcmlwdGlvbiA/PyBgUkVTVCBBUEkgZm9yICR7YXBpTmFtZX0gc2VydmljZWAsXG4gICAgICBkZWZhdWx0Q29yc1ByZWZsaWdodE9wdGlvbnM6IHtcbiAgICAgICAgYWxsb3dPcmlnaW5zOiBjb3JzT3B0aW9ucz8uYWxsb3dPcmlnaW5zID8/IENvcnMuQUxMX09SSUdJTlMsXG4gICAgICAgIGFsbG93TWV0aG9kczogW1xuICAgICAgICAgIFwiR0VUXCIsXG4gICAgICAgICAgXCJPUFRJT05TXCIsXG4gICAgICAgICAgLi4uKGNvcnNPcHRpb25zPy5hZGRpdGlvbmFsTWV0aG9kcyA/PyBbXSksXG4gICAgICAgIF0sXG4gICAgICAgIGFsbG93SGVhZGVyczogW1xuICAgICAgICAgIFwiQ29udGVudC1UeXBlXCIsXG4gICAgICAgICAgXCJYLUFwaS1LZXlcIixcbiAgICAgICAgICAuLi4oY29yc09wdGlvbnM/LmFkZGl0aW9uYWxIZWFkZXJzID8/IFtdKSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgfSk7XG5cbiAgICBmb3IgKGNvbnN0IHJvdXRlIG9mIHJvdXRlcykge1xuICAgICAgY29uc3QgcmVzb3VyY2UgPSB0aGlzLmFwaS5yb290LmFkZFJlc291cmNlKHJvdXRlLnBhdGgucmVwbGFjZSgvXlxcLy8sIFwiXCIpKTtcbiAgICAgIGZvciAoY29uc3QgbWV0aG9kIG9mIHJvdXRlLm1ldGhvZHMpIHtcbiAgICAgICAgcmVzb3VyY2UuYWRkTWV0aG9kKG1ldGhvZCwgcm91dGUuaW50ZWdyYXRpb24sIHsgYXBpS2V5UmVxdWlyZWQ6IHRydWUgfSk7XG4gICAgICB9XG4gICAgfVxuXG4gICAgdGhpcy5hcGlLZXkgPSBuZXcgQXBpS2V5KHRoaXMsIFwiQXBpS2V5XCIsIHtcbiAgICAgIGRlc2NyaXB0aW9uOiBgQVBJIEtleSBmb3IgJHthcGlOYW1lfSBzZXJ2aWNlYCxcbiAgICAgIGFwaUtleU5hbWU6IGFwaUtleU5hbWUgPz8gYCR7YXBpTmFtZX0tYXBpLWtleWAsXG4gICAgfSk7XG5cbiAgICB0aGlzLnVzYWdlUGxhbiA9IG5ldyBVc2FnZVBsYW4odGhpcywgXCJVc2FnZVBsYW5cIiwge1xuICAgICAgbmFtZTogdXNhZ2VQbGFuTmFtZSA/PyBgJHthcGlOYW1lfS11c2FnZS1wbGFuYCxcbiAgICAgIGRlc2NyaXB0aW9uOiBgVXNhZ2UgcGxhbiBmb3IgJHthcGlOYW1lfSBzZXJ2aWNlYCxcbiAgICAgIHRocm90dGxlLFxuICAgIH0pO1xuXG4gICAgdGhpcy51c2FnZVBsYW4uYWRkQXBpU3RhZ2Uoe1xuICAgICAgYXBpOiB0aGlzLmFwaSBhcyBJUmVzdEFwaSxcbiAgICAgIHN0YWdlOiB0aGlzLmFwaS5kZXBsb3ltZW50U3RhZ2UsXG4gICAgfSk7XG4gICAgdGhpcy51c2FnZVBsYW4uYWRkQXBpS2V5KHRoaXMuYXBpS2V5KTtcbiAgfVxufVxuIl19

package/lib/secure-rest-api.test.ts

@@ -0,0 +1,308 @@
+import { App, Stack } from "aws-cdk-lib";
+import { Template } from "aws-cdk-lib/assertions";
+import { LambdaIntegration, MockIntegration } from "aws-cdk-lib/aws-apigateway";
+import { HttpMethod } from "aws-cdk-lib/aws-apigatewayv2";
+import { Function, InlineCode, Runtime } from "aws-cdk-lib/aws-lambda";
+import { Construct } from "constructs";
+import { SecureRestApi } from "./secure-rest-api";
+
+const createStack = () => {
+  const app = new App();
+  const stack = new Stack(app, "TestStack");
+  return { app, stack };
+};
+
+const mockIntegration = () =>
+  new MockIntegration({
+    integrationResponses: [{ statusCode: "200" }],
+  });
+
+const lambdaIntegration = (scope: Construct) => {
+  const fn = new Function(scope, "Handler", {
+    runtime: Runtime.NODEJS_22_X,
+    handler: "index.handler",
+    code: InlineCode.fromInline("exports.handler = () => {}"),
+  });
+  return new LambdaIntegration(fn);
+};
+
+describe("SecureRestApi", () => {
+  describe("API Gateway", () => {
+    it("creates a REST API with the given name", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::RestApi",
+        { Name: "my-api" }
+      );
+    });
+
+    it("uses the provided description", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        description: "Custom description",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::RestApi",
+        { Description: "Custom description" }
+      );
+    });
+
+    it("registers each route method with apiKeyRequired", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET, HttpMethod.POST],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      const template = Template.fromStack(stack);
+      template.hasResourceProperties("AWS::ApiGateway::Method", {
+        HttpMethod: "GET",
+        ApiKeyRequired: true,
+      });
+      template.hasResourceProperties("AWS::ApiGateway::Method", {
+        HttpMethod: "POST",
+        ApiKeyRequired: true,
+      });
+    });
+
+    it("accepts a LambdaIntegration as route integration", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: lambdaIntegration(stack),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).resourceCountIs("AWS::Lambda::Function", 1);
+    });
+  });
+
+  describe("API Key", () => {
+    it("creates an API key with a default name", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::ApiKey",
+        { Name: "my-api-api-key" }
+      );
+    });
+
+    it("uses a custom API key name when provided", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        apiKeyName: "custom-key",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::ApiKey",
+        { Name: "custom-key" }
+      );
+    });
+  });
+
+  describe("Usage Plan", () => {
+    it("creates a usage plan with default throttle settings", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::UsagePlan",
+        {
+          Throttle: {
+            BurstLimit: 200,
+            RateLimit: 100,
+          },
+        }
+      );
+    });
+
+    it("uses custom throttle settings when provided", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        throttle: { rateLimit: 50, burstLimit: 100 },
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::UsagePlan",
+        {
+          Throttle: {
+            BurstLimit: 100,
+            RateLimit: 50,
+          },
+        }
+      );
+    });
+
+    it("uses a custom usage plan name when provided", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        usagePlanName: "custom-plan",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::UsagePlan",
+        { UsagePlanName: "custom-plan" }
+      );
+    });
+  });
+
+  describe("CORS", () => {
+    it("applies default CORS settings", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::Method",
+        { HttpMethod: "OPTIONS" }
+      );
+    });
+
+    it("appends additionalHeaders to the defaults", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        corsOptions: { additionalHeaders: ["Authorization"] },
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      // OPTIONS mock integration response headers include the allow-headers value
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::Method",
+        {
+          HttpMethod: "OPTIONS",
+          Integration: {
+            IntegrationResponses: [
+              {
+                ResponseParameters: {
+                  "method.response.header.Access-Control-Allow-Headers":
+                    "'Content-Type,X-Api-Key,Authorization'",
+                },
+              },
+            ],
+          },
+        }
+      );
+    });
+
+    it("appends additionalMethods to the defaults", () => {
+      const { stack } = createStack();
+      new SecureRestApi(stack, "Api", {
+        apiName: "my-api",
+        corsOptions: { additionalMethods: ["POST"] },
+        routes: [
+          {
+            path: "items",
+            methods: [HttpMethod.GET],
+            integration: mockIntegration(),
+          },
+        ],
+      });
+
+      Template.fromStack(stack).hasResourceProperties(
+        "AWS::ApiGateway::Method",
+        {
+          HttpMethod: "OPTIONS",
+          Integration: {
+            IntegrationResponses: [
+              {
+                ResponseParameters: {
+                  "method.response.header.Access-Control-Allow-Methods":
+                    "'GET,OPTIONS,POST'",
+                },
+              },
+            ],
+          },
+        }
+      );
+    });
+  });
+});

package/lib/secure-rest-api.ts

@@ -0,0 +1,129 @@
+import {
+  ApiKey,
+  Cors,
+  Integration,
+  IRestApi,
+  RestApi,
+  UsagePlan,
+} from "aws-cdk-lib/aws-apigateway";
+import { HttpMethod } from "aws-cdk-lib/aws-apigatewayv2";
+import { Construct } from "constructs";
+
+export interface SecureRestApiRoute {
+  path: string;
+  methods: HttpMethod[];
+  integration: Integration;
+}
+
+export interface SecureRestApiProps {
+  /**
+   * The name of the API.
+   */
+  apiName: string;
+
+  /**
+   * Description for the API.
+   */
+  description?: string;
+
+  /**
+   * CORS configuration.
+   *
+   * `allowOrigins` overrides the default (all origins).
+   * `additionalMethods` and `additionalHeaders` are appended to the defaults
+   * (GET/OPTIONS and Content-Type/X-Api-Key respectively).
+   */
+  corsOptions?: {
+    allowOrigins?: string[];
+    additionalMethods?: string[];
+    additionalHeaders?: string[];
+  };
+
+  /**
+   * Routes to register on the API.
+   */
+  routes: SecureRestApiRoute[];
+
+  /**
+   * Throttling limits for the usage plan.
+   * @default { rateLimit: 100, burstLimit: 200 }
+   */
+  throttle?: {
+    rateLimit: number;
+    burstLimit: number;
+  };
+
+  /**
+   * Override the generated API key name.
+   * @default `{apiName}-api-key`
+   */
+  apiKeyName?: string;
+
+  /**
+   * Override the generated usage plan name.
+   * @default `{apiName}-usage-plan`
+   */
+  usagePlanName?: string;
+}
+
+export class SecureRestApi extends Construct {
+  public readonly api: RestApi;
+  public readonly apiKey: ApiKey;
+  public readonly usagePlan: UsagePlan;
+
+  constructor(scope: Construct, id: string, props: SecureRestApiProps) {
+    super(scope, id);
+
+    const {
+      apiName,
+      description,
+      corsOptions,
+      routes,
+      throttle = { rateLimit: 100, burstLimit: 200 },
+      apiKeyName,
+      usagePlanName,
+    } = props;
+
+    this.api = new RestApi(this, "Api", {
+      restApiName: apiName,
+      description: description ?? `REST API for ${apiName} service`,
+      defaultCorsPreflightOptions: {
+        allowOrigins: corsOptions?.allowOrigins ?? Cors.ALL_ORIGINS,
+        allowMethods: [
+          "GET",
+          "OPTIONS",
+          ...(corsOptions?.additionalMethods ?? []),
+        ],
+        allowHeaders: [
+          "Content-Type",
+          "X-Api-Key",
+          ...(corsOptions?.additionalHeaders ?? []),
+        ],
+      },
+    });
+
+    for (const route of routes) {
+      const resource = this.api.root.addResource(route.path.replace(/^\//, ""));
+      for (const method of route.methods) {
+        resource.addMethod(method, route.integration, { apiKeyRequired: true });
+      }
+    }
+
+    this.apiKey = new ApiKey(this, "ApiKey", {
+      description: `API Key for ${apiName} service`,
+      apiKeyName: apiKeyName ?? `${apiName}-api-key`,
+    });
+
+    this.usagePlan = new UsagePlan(this, "UsagePlan", {
+      name: usagePlanName ?? `${apiName}-usage-plan`,
+      description: `Usage plan for ${apiName} service`,
+      throttle,
+    });
+
+    this.usagePlan.addApiStage({
+      api: this.api as IRestApi,
+      stage: this.api.deploymentStage,
+    });
+    this.usagePlan.addApiKey(this.apiKey);
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@aligent/cdk-secure-rest-api",
+  "version": "1.1.0",
+  "description": "A CDK construct for creating API Gateway REST APIs secured with API Key authentication and usage plan throttling",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "homepage": "https://github.com/aligent/cdk-constructs/tree/main/packages/constructs/secure-rest-api#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aligent/cdk-constructs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aligent/cdk-constructs/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npx nx test secure-rest-api",
+    "lint": "npx nx lint secure-rest-api"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.10",
+    "@types/node": "^20.19.39",
+    "aws-cdk": "^2.1120.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.2"
+  },
+  "dependencies": {
+    "source-map-support": "^0.5.21"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.113.0",
+    "constructs": "^10.5.0"
+  }
+}

package/project.json

@@ -0,0 +1,36 @@
+{
+  "name": "secure-rest-api",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/constructs/secure-rest-api/lib",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc --project tsconfig.app.json",
+        "cwd": "packages/constructs/secure-rest-api"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"]
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "packages/constructs/secure-rest-api/jest.config.ts",
+        "passWithNoTests": true
+      }
+    },
+    "publish": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "npm publish --access public",
+        "cwd": "packages/constructs/secure-rest-api"
+      },
+      "dependsOn": ["build"]
+    }
+  },
+  "tags": []
+}

package/tsconfig.app.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": ".",
+    "rootDir": ".",
+    "module": "commonjs",
+    "types": ["node"]
+  },
+  "exclude": ["./jest.config.ts", "**/*.test.ts", "**/*.spec.ts"],
+  "include": ["lib/**/*.ts", "index.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ],
+  "compilerOptions": {
+    "esModuleInterop": true
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node"]
+  }
+}