rds-database-auto-start-preventer 0.4.4 → 0.5.0

package/.editorconfig

@@ -9,4 +9,4 @@ charset=utf-8
 [*\.{js,ts}]
 indent_style=space
 indent_size=2
-max_line_length=120
+max_line_length=160

package/.jsii

@@ -8435,7 +8435,7 @@
       }
     }
   },
-  "description": "CDK stack that stops RDS DB instances and clusters after they are auto-started by AWS (RDS-EVENT-0154 / RDS-EVENT-0153). It uses EventBridge rules and a Durable Lambda to detect auto-start events, optionally filter by tags, stop the resource if it matches, and post a notification to Slack.",
+  "description": "CDK construct library that stops RDS DB instances and clusters after they are auto-started by AWS (RDS-EVENT-0154 / RDS-EVENT-0153), using EventBridge and a Durable Lambda to filter by tags in the handler, stop matching available resources, and post to Slack only after a successful stop when a Slack secret name is set.",
   "docs": {
     "stability": "stable"
   },
@@ -8459,7 +8459,7 @@
   },
   "name": "rds-database-auto-start-preventer",
   "readme": {
-    "markdown": "# RDS Database Auto Start Preventer (CDK v2)\n\n[![npm version](https://img.shields.io/npm/v/rds-database-auto-start-preventer?style=flat-square)](https://www.npmjs.com/package/rds-database-auto-start-preventer)\n[![license](https://img.shields.io/npm/l/rds-database-auto-start-preventer?style=flat-square)](https://www.npmjs.com/package/rds-database-auto-start-preventer)\n[![Node.js](https://img.shields.io/node/v/rds-database-auto-start-preventer?style=flat-square)](https://www.npmjs.com/package/rds-database-auto-start-preventer)\n[![build](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/rds-database-auto-start-preventer/build.yml?label=build&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/rds-database-auto-start-preventer/actions/workflows/build.yml)\n\n[![View on Construct Hub](https://constructs.dev/badge?package=rds-database-auto-start-preventer)](https://constructs.dev/packages/rds-database-auto-start-preventer)\n\nCDK construct library that stops RDS DB instances and clusters after they are auto-started by AWS (RDS-EVENT-0154 / RDS-EVENT-0153). It uses EventBridge rules and a Durable Lambda to detect auto-start events, filter resources by tags in the handler, stop matching resources when they are `available`, and post a Slack notification only when this Lambda invoked the stop API successfully and a Slack secret name is set.\n\n## Features\n\n- **EventBridge integration** – Listens for RDS DB Instance (RDS-EVENT-0154) and DB Cluster (RDS-EVENT-0153) auto-start events\n- **Handler-side tag filtering** – EventBridge rules match all auto-start events; the Lambda evaluates `TagList` from `rds:DescribeDBInstances` / `rds:DescribeDBClusters` and skips resources that do not match `tagKey` / `tagValues`\n- **Durable Lambda** – Uses AWS Lambda Durable Execution for reliable, long-running workflow (initial wait, status wait, stop, and post-stop wait)\n- **Least-privilege IAM** – Grants RDS describe and stop actions only (no Resource Groups Tagging API)\n- **Slack notifications** – When `slackSecretName` is set, sends a message when this invocation called `StopDBInstance` / `StopDBCluster` and the resource reached `stopped` (no notification when the secret name is omitted, the resource was already stopped, or tags did not match)\n- **Optional rule toggle** – EventBridge rules can be enabled or disabled via `enableRule`\n\n## How it works\n\n1. EventBridge invokes the Durable Lambda with the RDS auto-start event and tag filter parameters (`tagKey`, `tagValues`).\n2. The handler waits 1 minute, then waits on DescribeDB* until the resource leaves transitional statuses.\n3. If the resource tag does not match, the handler exits with no stop action.\n4. If the resource is `available` and tags match, the handler calls StopDB* and waits until `stopped`.\n5. If the resource is already `stopped` (for example, stopped by another process), the handler exits without calling StopDB* and without posting to Slack.\n6. When `slackSecretName` is set, Slack is notified only when StopDB* was invoked by this invocation and the resource reached `stopped`. When it is omitted, the handler does not post to Slack.\n\nTag the RDS instances or clusters you want to protect (for example, `AutoStartPrevent=YES`). Resources without a matching tag are left running.\n\n## Installation\n\n### npm\n\n```bash\nnpm install rds-database-auto-start-preventer\n```\n\n### yarn\n\n```bash\nyarn add rds-database-auto-start-preventer\n```\n\n### pnpm\n\n```bash\npnpm add rds-database-auto-start-preventer\n```\n\n## Usage\n\nUse `RDSDatabaseAutoStartPreventer` when you want to add auto-start prevention to an existing stack or compose it with other constructs. Omit `slackSecretName` to stop matching resources without Slack.\n\n```typescript\nimport { App, Stack } from 'aws-cdk-lib';\nimport { RDSDatabaseAutoStartPreventer } from 'rds-database-auto-start-preventer';\n\nconst app = new App();\nconst stack = new Stack(app, 'MyStack');\n\nnew RDSDatabaseAutoStartPreventer(stack, 'RDSDatabaseAutoStartPreventer', {\n  targetResource: {\n    tagKey: 'AutoStartPrevent',\n    tagValues: ['YES'],\n  },\n  secrets: {},\n});\n```\n\nPass `slackSecretName` when a successful stop should post to Slack. `enableRule` defaults to `true`.\n\n```typescript\nnew RDSDatabaseAutoStartPreventer(stack, 'RDSDatabaseAutoStartPreventer', {\n  targetResource: {\n    tagKey: 'AutoStartPrevent',\n    tagValues: ['YES'],\n  },\n  enableRule: true,\n  secrets: {\n    slackSecretName: 'my-app/slack',\n  },\n});\n```\n\n### Stack\n\nUse `RDSDatabaseAutoStartPreventStack` when you want a dedicated stack that only deploys the RDS auto-start prevent resources.\n\n```typescript\nimport { App } from 'aws-cdk-lib';\nimport { RDSDatabaseAutoStartPreventStack } from 'rds-database-auto-start-preventer';\n\nconst app = new App();\n\nnew RDSDatabaseAutoStartPreventStack(app, 'RDSDatabaseAutoStartPreventStack', {\n  stackName: 'rds-database-auto-start-prevent',\n  targetResource: {\n    tagKey: 'AutoStartPrevent',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-app/slack',\n  },\n});\n```\n\n### Slack secret (AWS Secrets Manager)\n\nStore a JSON object in AWS Secrets Manager with the Slack Bot Token and channel ID:\n\n| Key | Value |\n|-----|-------|\n| `token` | Slack Bot Token (e.g. `xoxb-...`) |\n| `channel` | Slack channel ID (e.g. `C01234ABCD`) |\n\nExample secret value:\n\n```json\n{\n  \"token\": \"xoxb-...\",\n  \"channel\": \"C01234ABCD\"\n}\n```\n\n## Options\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `targetResource` | `TargetResource` | Yes | Tag-based criteria evaluated in the Lambda handler. |\n| `targetResource.tagKey` | `string` | Yes | Tag key to match (e.g. `AutoStartPrevent`, `Environment`). |\n| `targetResource.tagValues` | `string[]` | Yes | Tag values that indicate the resource should be stopped (e.g. `['YES']`, `['production']`). |\n| `enableRule` | `boolean` | No | Whether the EventBridge rules are enabled. Defaults to `true` if omitted. |\n| `secrets` | `Secrets` | Yes | External secrets for notifications. |\n| `secrets.slackSecretName` | `string` | No | Name of the Secrets Manager secret containing Slack `token` and `channel`. Omit it to skip Slack notifications. |\n\nEmpty `tagKey`, an empty `tagValues` array (or blank entries), and a blank `slackSecretName` fail at synthesis. Omitting `slackSecretName` is allowed. Unresolved CDK tokens are not checked.\n\n## API\n\nSee [API.md](./API.md).\n\n## Requirements\n\n- **Node.js** >= 20.0.0 (for your CDK app)\n- **AWS CDK** ^2.232.0\n- **constructs** ^10.5.1\n- **AWS Lambda** runtime Node.js 24.x with Durable Execution (deployed by the construct)\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
+    "markdown": "# RDS Database Auto Start Preventer (CDK v2)\n\n[![npm version](https://img.shields.io/npm/v/rds-database-auto-start-preventer?style=flat-square)](https://www.npmjs.com/package/rds-database-auto-start-preventer)\n[![license](https://img.shields.io/npm/l/rds-database-auto-start-preventer?style=flat-square)](https://www.npmjs.com/package/rds-database-auto-start-preventer)\n[![Node.js](https://img.shields.io/node/v/rds-database-auto-start-preventer?style=flat-square)](https://www.npmjs.com/package/rds-database-auto-start-preventer)\n[![build](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/rds-database-auto-start-preventer/build.yml?label=build&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/rds-database-auto-start-preventer/actions/workflows/build.yml)\n\n[![View on Construct Hub](https://constructs.dev/badge?package=rds-database-auto-start-preventer)](https://constructs.dev/packages/rds-database-auto-start-preventer)\n\nCDK construct library that stops RDS DB instances and clusters after they are auto-started by AWS (RDS-EVENT-0154 / RDS-EVENT-0153). It uses EventBridge rules and a Durable Lambda to detect auto-start events, filter resources by tags in the handler, stop matching resources when they are `available`, and post a Slack notification only when this Lambda invoked the stop API successfully and a Slack secret name is set.\n\n## Features\n\n- **EventBridge integration** – Listens for RDS DB Instance (RDS-EVENT-0154) and DB Cluster (RDS-EVENT-0153) auto-start events\n- **Handler-side tag filtering** – EventBridge rules match all auto-start events; the Lambda evaluates `TagList` from `rds:DescribeDBInstances` / `rds:DescribeDBClusters`. Tag mismatch is a no-op (no StopDB*, no Slack)\n- **Durable Lambda** – Uses AWS Lambda Durable Execution for a long-running workflow (initial wait, status wait, stop, and post-stop wait) with a 2-hour execution timeout\n- **Least-privilege IAM** – Describe is scoped to account/region `db` / `cluster` ARNs; Stop is further limited by `aws:ResourceTag` matching `tagKey` / `tagValues` (no Resource Groups Tagging API)\n- **Slack notifications** – When `slackSecretName` is set, sends a message when this invocation called `StopDBInstance` / `StopDBCluster` and the resource reached `stopped` (no notification when the secret name is omitted, the resource was already stopped, or tags did not match)\n- **Optional rule toggle** – EventBridge rules can be enabled or disabled via `enableRule`\n\n## How it works\n\n1. EventBridge invokes the Durable Lambda with the RDS auto-start event and tag filter parameters (`tagKey`, `tagValues`).\n2. The handler waits **1 minute**, then calls DescribeDB* until the resource leaves transitional statuses. While the status stays transitional (or stopping after StopDB*), it waits up to **5 minutes** between describes.\n3. If the resource tag does not match, the handler exits as a **no-op** (no StopDB*, no Slack).\n4. If the resource is `available` and tags match, the handler calls StopDB* and waits until `stopped` (again using up to 5-minute intervals while transitional).\n5. If the resource is already `stopped` (for example, stopped by another process), the handler exits without calling StopDB* and without posting to Slack.\n6. When `slackSecretName` is set, Slack is notified only when StopDB* was invoked by this invocation and the resource reached `stopped`. When it is omitted, the handler does not post to Slack.\n\nTiming defaults (not configurable via props today):\n\n| Setting | Value |\n|---------|-------|\n| Initial wait before the first describe | 1 minute |\n| Wait between describes while status is transitional / stopping | up to 5 minutes |\n| Lambda invocation `timeout` | 15 minutes |\n| Durable `executionTimeout` | 2 hours |\n| Durable history `retentionPeriod` | 1 day |\n\nTag the RDS instances or clusters you want to protect (for example, `AutoStartPrevent=YES`). Resources without a matching tag are left running (no-op).\n\n## Installation\n\n### npm\n\n```bash\nnpm install rds-database-auto-start-preventer\n```\n\n### yarn\n\n```bash\nyarn add rds-database-auto-start-preventer\n```\n\n### pnpm\n\n```bash\npnpm add rds-database-auto-start-preventer\n```\n\n## Usage\n\n### Minimal deployable app\n\nUse `RDSDatabaseAutoStartPreventStack` when you want a dedicated stack you can deploy as-is. Put this in your CDK app entry (for example `bin/app.ts`), then deploy.\n\n```typescript\nimport { App } from 'aws-cdk-lib';\nimport { RDSDatabaseAutoStartPreventStack } from 'rds-database-auto-start-preventer';\n\nconst app = new App();\n\nnew RDSDatabaseAutoStartPreventStack(app, 'RDSDatabaseAutoStartPreventStack', {\n  env: {\n    account: process.env.CDK_DEFAULT_ACCOUNT,\n    region: process.env.CDK_DEFAULT_REGION,\n  },\n  stackName: 'rds-database-auto-start-prevent',\n  targetResource: {\n    tagKey: 'AutoStartPrevent',\n    tagValues: ['YES'],\n  },\n  // Omit slackSecretName to skip Slack; set it when stop should notify Slack.\n  secrets: {\n    slackSecretName: 'my-app/slack',\n  },\n});\n\napp.synth();\n```\n\nDeploy checklist:\n\n1. Install this package and peers (`aws-cdk-lib`, `constructs`) in your CDK app.\n2. Tag the RDS instances or clusters to protect (for example `AutoStartPrevent=YES`).\n3. Optional: create the Secrets Manager secret described in [Slack secret](#slack-secret-aws-secrets-manager). Omit `slackSecretName` if you do not need Slack.\n4. From the CDK app: `npx cdk deploy RDSDatabaseAutoStartPreventStack`\n\n### Construct in an existing stack\n\nUse `RDSDatabaseAutoStartPreventer` when you want to add auto-start prevention to an existing stack or compose it with other constructs. Omit `slackSecretName` to stop matching resources without Slack.\n\n```typescript\nimport { App, Stack } from 'aws-cdk-lib';\nimport { RDSDatabaseAutoStartPreventer } from 'rds-database-auto-start-preventer';\n\nconst app = new App();\nconst stack = new Stack(app, 'MyStack');\n\nnew RDSDatabaseAutoStartPreventer(stack, 'RDSDatabaseAutoStartPreventer', {\n  targetResource: {\n    tagKey: 'AutoStartPrevent',\n    tagValues: ['YES'],\n  },\n  secrets: {},\n});\n```\n\nPass `slackSecretName` when a successful stop should post to Slack. `enableRule` defaults to `true`.\n\n```typescript\nnew RDSDatabaseAutoStartPreventer(stack, 'RDSDatabaseAutoStartPreventer', {\n  targetResource: {\n    tagKey: 'AutoStartPrevent',\n    tagValues: ['YES'],\n  },\n  enableRule: true,\n  secrets: {\n    slackSecretName: 'my-app/slack',\n  },\n});\n```\n\n### Slack secret (AWS Secrets Manager)\n\nCreate the secret **before** deploy when you want Slack notifications. Omit `slackSecretName` to skip Slack entirely (no secret and no Secrets Manager IAM are required in that case).\n\nStore a JSON object in AWS Secrets Manager with the Slack Bot Token and channel ID:\n\n| Key | Value |\n|-----|-------|\n| `token` | Slack Bot Token (e.g. `xoxb-...`) |\n| `channel` | Slack channel ID (e.g. `C01234ABCD`) |\n\nExample secret value:\n\n```json\n{\n  \"token\": \"xoxb-...\",\n  \"channel\": \"C01234ABCD\"\n}\n```\n\nWhen `slackSecretName` is set, the construct grants the Lambda role read access to that secret and attaches the AWS Parameters and Secrets Extension. You do not need to add a separate Secrets Manager policy yourself for this secret.\n\n## Options\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `targetResource` | `TargetResource` | Yes | Tag-based criteria evaluated in the Lambda handler. |\n| `targetResource.tagKey` | `string` | Yes | Tag key to match (e.g. `AutoStartPrevent`, `Environment`). |\n| `targetResource.tagValues` | `string[]` | Yes | Tag values that indicate the resource should be stopped (e.g. `['YES']`, `['production']`). |\n| `enableRule` | `boolean` | No | Whether the EventBridge rules are enabled. Defaults to `true` if omitted. |\n| `secrets` | `Secrets` | Yes | External secrets for notifications. |\n| `secrets.slackSecretName` | `string` | No | Name of the Secrets Manager secret containing Slack `token` and `channel`. Omit it to skip Slack notifications. |\n\nEmpty `tagKey`, an empty `tagValues` array (or blank entries), and a blank `slackSecretName` fail at synthesis. Omitting `slackSecretName` is allowed. Unresolved CDK tokens are not checked.\n\n## API\n\nSee [API.md](./API.md).\n\n## Requirements\n\n- **Node.js** >= 20.0.0 (for your CDK app)\n- **AWS CDK** ^2.232.0\n- **constructs** ^10.5.1\n- **AWS Lambda** runtime Node.js 24.x with Durable Execution (deployed by the construct)\n\n## Notes\n\n- **Aurora / dual events:** An Aurora auto-start can emit both a DB cluster event (`RDS-EVENT-0153`) and DB instance event(s) (`RDS-EVENT-0154`). This package listens for both and may run separate Durable executions. Tag mismatch remains a no-op; if the resource is already `stopped`, the handler does not call StopDB* and does not post to Slack.\n- **IAM:** RDS Describe is limited to account/region `db` / `cluster` ARNs. Stop requires a matching `aws:ResourceTag` for your `tagKey` / `tagValues`. Slack secret read is granted only when `slackSecretName` is set.\n\n## Troubleshooting\n\n- **CloudWatch Logs:** The construct creates a dedicated Log Group for the Durable Lambda (JSON logs, 3-month retention). After a successful create, the log group uses `RetainExceptOnCreate` so it remains available for incident review after stack delete or replace.\n- **Nothing stopped / no Slack:** Confirm the resource tag matches `tagKey` / `tagValues`. Mismatch is intentional no-op with no Slack message.\n- **Stop attempted but Slack missing:** Slack runs only when this invocation called StopDB* and the resource reached `stopped`, and only when `slackSecretName` is set. Already-stopped resources skip Slack.\n- **Secret errors:** Ensure the secret exists before deploy, JSON has non-empty `token` and `channel`, and the name passed as `slackSecretName` matches Secrets Manager.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
   },
   "repository": {
     "type": "git",
@@ -8486,8 +8486,8 @@
           "summary": "Creates the stack and the RDSDatabaseAutoStartPreventer construct."
         },
         "locationInModule": {
-          "filename": "src/stacks/rds-database-auto-start-prevent-stack.ts",
-          "line": 29
+          "filename": "src/rds-database-auto-start-prevent-stack.ts",
+          "line": 24
         },
         "parameters": [
           {
@@ -8521,11 +8521,11 @@
       },
       "kind": "class",
       "locationInModule": {
-        "filename": "src/stacks/rds-database-auto-start-prevent-stack.ts",
-        "line": 21
+        "filename": "src/rds-database-auto-start-prevent-stack.ts",
+        "line": 16
       },
       "name": "RDSDatabaseAutoStartPreventStack",
-      "symbolId": "src/stacks/rds-database-auto-start-prevent-stack:RDSDatabaseAutoStartPreventStack"
+      "symbolId": "src/rds-database-auto-start-prevent-stack:RDSDatabaseAutoStartPreventStack"
     },
     "rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps": {
       "assembly": "rds-database-auto-start-preventer",
@@ -8536,74 +8536,22 @@
       },
       "fqn": "rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps",
       "interfaces": [
+        "rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventerProps",
         "aws-cdk-lib.StackProps"
       ],
       "kind": "interface",
       "locationInModule": {
-        "filename": "src/stacks/rds-database-auto-start-prevent-stack.ts",
-        "line": 9
+        "filename": "src/rds-database-auto-start-prevent-stack.ts",
+        "line": 11
       },
       "name": "RDSDatabaseAutoStartPreventStackProps",
-      "properties": [
-        {
-          "abstract": true,
-          "docs": {
-            "remarks": "Omit slackSecretName to skip Slack.",
-            "stability": "stable",
-            "summary": "Secrets for notifications."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/stacks/rds-database-auto-start-prevent-stack.ts",
-            "line": 15
-          },
-          "name": "secrets",
-          "type": {
-            "fqn": "rds-database-auto-start-preventer.Secrets"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "stability": "stable",
-            "summary": "Tag-based target resource criteria for RDS instances/clusters to protect."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/stacks/rds-database-auto-start-prevent-stack.ts",
-            "line": 11
-          },
-          "name": "targetResource",
-          "type": {
-            "fqn": "rds-database-auto-start-preventer.TargetResource"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "remarks": "Defaults to true if omitted.",
-            "stability": "stable",
-            "summary": "Whether the EventBridge rules are enabled."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/stacks/rds-database-auto-start-prevent-stack.ts",
-            "line": 13
-          },
-          "name": "enableRule",
-          "optional": true,
-          "type": {
-            "primitive": "boolean"
-          }
-        }
-      ],
-      "symbolId": "src/stacks/rds-database-auto-start-prevent-stack:RDSDatabaseAutoStartPreventStackProps"
+      "symbolId": "src/rds-database-auto-start-prevent-stack:RDSDatabaseAutoStartPreventStackProps"
     },
     "rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventer": {
       "assembly": "rds-database-auto-start-preventer",
       "base": "constructs.Construct",
       "docs": {
-        "remarks": "EventBridge rules match all auto-start events; tag filtering runs in the handler\nusing `TagList` from `rds:DescribeDBInstances` / `rds:DescribeDBClusters`.\nIAM grants RDS describe and stop actions only (no Resource Groups Tagging API).",
+        "remarks": "EventBridge rules match all auto-start events; tag filtering runs in the handler\nusing `TagList` from `rds:DescribeDBInstances` / `rds:DescribeDBClusters`.\nIAM grants account/region-scoped describe on `db` / `cluster` ARNs, and stop only\nwhen `aws:ResourceTag` matches {@link TargetResource} (no Resource Groups Tagging API).",
         "stability": "stable",
         "summary": "Deploys EventBridge rules and a Durable Lambda to stop matching RDS resources after auto-start events (RDS-EVENT-0154 / RDS-EVENT-0153)."
       },
@@ -8618,8 +8566,8 @@
           "summary": "Creates the Durable Lambda, EventBridge rules, and IAM policies."
         },
         "locationInModule": {
-          "filename": "src/constructs/rds-database-auto-start-preventer.ts",
-          "line": 103
+          "filename": "src/rds-database-auto-start-preventer.ts",
+          "line": 104
         },
         "parameters": [
           {
@@ -8653,11 +8601,11 @@
       },
       "kind": "class",
       "locationInModule": {
-        "filename": "src/constructs/rds-database-auto-start-preventer.ts",
-        "line": 89
+        "filename": "src/rds-database-auto-start-preventer.ts",
+        "line": 90
       },
       "name": "RDSDatabaseAutoStartPreventer",
-      "symbolId": "src/constructs/rds-database-auto-start-preventer:RDSDatabaseAutoStartPreventer"
+      "symbolId": "src/rds-database-auto-start-preventer:RDSDatabaseAutoStartPreventer"
     },
     "rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventerProps": {
       "assembly": "rds-database-auto-start-preventer",
@@ -8669,7 +8617,7 @@
       "fqn": "rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventerProps",
       "kind": "interface",
       "locationInModule": {
-        "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+        "filename": "src/rds-database-auto-start-preventer.ts",
         "line": 38
       },
       "name": "RDSDatabaseAutoStartPreventerProps",
@@ -8682,7 +8630,7 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+            "filename": "src/rds-database-auto-start-preventer.ts",
             "line": 44
           },
           "name": "secrets",
@@ -8698,7 +8646,7 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+            "filename": "src/rds-database-auto-start-preventer.ts",
             "line": 40
           },
           "name": "targetResource",
@@ -8715,7 +8663,7 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+            "filename": "src/rds-database-auto-start-preventer.ts",
             "line": 42
           },
           "name": "enableRule",
@@ -8725,7 +8673,7 @@
           }
         }
       ],
-      "symbolId": "src/constructs/rds-database-auto-start-preventer:RDSDatabaseAutoStartPreventerProps"
+      "symbolId": "src/rds-database-auto-start-preventer:RDSDatabaseAutoStartPreventerProps"
     },
     "rds-database-auto-start-preventer.Secrets": {
       "assembly": "rds-database-auto-start-preventer",
@@ -8737,7 +8685,7 @@
       "fqn": "rds-database-auto-start-preventer.Secrets",
       "kind": "interface",
       "locationInModule": {
-        "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+        "filename": "src/rds-database-auto-start-preventer.ts",
         "line": 27
       },
       "name": "Secrets",
@@ -8751,7 +8699,7 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+            "filename": "src/rds-database-auto-start-preventer.ts",
             "line": 32
           },
           "name": "slackSecretName",
@@ -8761,7 +8709,7 @@
           }
         }
       ],
-      "symbolId": "src/constructs/rds-database-auto-start-preventer:Secrets"
+      "symbolId": "src/rds-database-auto-start-preventer:Secrets"
     },
     "rds-database-auto-start-preventer.TargetResource": {
       "assembly": "rds-database-auto-start-preventer",
@@ -8774,7 +8722,7 @@
       "fqn": "rds-database-auto-start-preventer.TargetResource",
       "kind": "interface",
       "locationInModule": {
-        "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+        "filename": "src/rds-database-auto-start-preventer.ts",
         "line": 16
       },
       "name": "TargetResource",
@@ -8787,7 +8735,7 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+            "filename": "src/rds-database-auto-start-preventer.ts",
             "line": 18
           },
           "name": "tagKey",
@@ -8803,7 +8751,7 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/constructs/rds-database-auto-start-preventer.ts",
+            "filename": "src/rds-database-auto-start-preventer.ts",
             "line": 20
           },
           "name": "tagValues",
@@ -8817,9 +8765,9 @@
           }
         }
       ],
-      "symbolId": "src/constructs/rds-database-auto-start-preventer:TargetResource"
+      "symbolId": "src/rds-database-auto-start-preventer:TargetResource"
     }
   },
-  "version": "0.4.4",
-  "fingerprint": "Ma7/fFGl2OmzwiEKzpwd1zN8oHuxcTuVbuOtR4Ca6IM="
+  "version": "0.5.0",
+  "fingerprint": "9sN1LILaadPIhBLYlDBY7yP/xKkSyy83hdp7G50Qa1s="
 }

package/API.md

@@ -8,7 +8,8 @@ Deploys EventBridge rules and a Durable Lambda to stop matching RDS resources af
 
 EventBridge rules match all auto-start events; tag filtering runs in the handler
 using `TagList` from `rds:DescribeDBInstances` / `rds:DescribeDBClusters`.
-IAM grants RDS describe and stop actions only (no Resource Groups Tagging API).
+IAM grants account/region-scoped describe on `db` / `cluster` ARNs, and stop only
+when `aws:ResourceTag` matches {@link TargetResource} (no Resource Groups Tagging API).
 
 #### Initializers <a name="Initializers" id="rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventer.Initializer"></a>
 
@@ -1184,6 +1185,9 @@ const rDSDatabaseAutoStartPreventStackProps: RDSDatabaseAutoStartPreventStackPro
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.secrets">secrets</a></code> | <code><a href="#rds-database-auto-start-preventer.Secrets">Secrets</a></code> | Secrets used for notifications (e.g. Slack). |
+| <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.targetResource">targetResource</a></code> | <code><a href="#rds-database-auto-start-preventer.TargetResource">TargetResource</a></code> | Tag-based target resource criteria for RDS instances/clusters to protect. |
+| <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.enableRule">enableRule</a></code> | <code>boolean</code> | Whether the EventBridge rules are enabled. |
 | <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.analyticsReporting">analyticsReporting</a></code> | <code>boolean</code> | Include runtime versioning information in this Stack. |
 | <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.crossRegionReferences">crossRegionReferences</a></code> | <code>boolean</code> | Enable this flag to allow native cross region stack references. |
 | <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.description">description</a></code> | <code>string</code> | A description of the stack. |
@@ -1196,9 +1200,44 @@ const rDSDatabaseAutoStartPreventStackProps: RDSDatabaseAutoStartPreventStackPro
 | <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.synthesizer">synthesizer</a></code> | <code>aws-cdk-lib.IStackSynthesizer</code> | Synthesis method to use while deploying this stack. |
 | <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.tags">tags</a></code> | <code>{[ key: string ]: string}</code> | Tags that will be applied to the Stack. |
 | <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.terminationProtection">terminationProtection</a></code> | <code>boolean</code> | Whether to enable termination protection for this stack. |
-| <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.secrets">secrets</a></code> | <code><a href="#rds-database-auto-start-preventer.Secrets">Secrets</a></code> | Secrets for notifications. |
-| <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.targetResource">targetResource</a></code> | <code><a href="#rds-database-auto-start-preventer.TargetResource">TargetResource</a></code> | Tag-based target resource criteria for RDS instances/clusters to protect. |
-| <code><a href="#rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.enableRule">enableRule</a></code> | <code>boolean</code> | Whether the EventBridge rules are enabled. |
+
+---
+
+##### `secrets`<sup>Required</sup> <a name="secrets" id="rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.secrets"></a>
+
+```typescript
+public readonly secrets: Secrets;
+```
+
+- *Type:* <a href="#rds-database-auto-start-preventer.Secrets">Secrets</a>
+
+Secrets used for notifications (e.g. Slack).
+
+---
+
+##### `targetResource`<sup>Required</sup> <a name="targetResource" id="rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.targetResource"></a>
+
+```typescript
+public readonly targetResource: TargetResource;
+```
+
+- *Type:* <a href="#rds-database-auto-start-preventer.TargetResource">TargetResource</a>
+
+Tag-based target resource criteria for RDS instances/clusters to protect.
+
+---
+
+##### `enableRule`<sup>Optional</sup> <a name="enableRule" id="rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.enableRule"></a>
+
+```typescript
+public readonly enableRule: boolean;
+```
+
+- *Type:* boolean
+
+Whether the EventBridge rules are enabled.
+
+Defaults to true if omitted.
 
 ---
 
@@ -1446,46 +1485,6 @@ Whether to enable termination protection for this stack.
 
 ---
 
-##### `secrets`<sup>Required</sup> <a name="secrets" id="rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.secrets"></a>
-
-```typescript
-public readonly secrets: Secrets;
-```
-
-- *Type:* <a href="#rds-database-auto-start-preventer.Secrets">Secrets</a>
-
-Secrets for notifications.
-
-Omit slackSecretName to skip Slack.
-
----
-
-##### `targetResource`<sup>Required</sup> <a name="targetResource" id="rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.targetResource"></a>
-
-```typescript
-public readonly targetResource: TargetResource;
-```
-
-- *Type:* <a href="#rds-database-auto-start-preventer.TargetResource">TargetResource</a>
-
-Tag-based target resource criteria for RDS instances/clusters to protect.
-
----
-
-##### `enableRule`<sup>Optional</sup> <a name="enableRule" id="rds-database-auto-start-preventer.RDSDatabaseAutoStartPreventStackProps.property.enableRule"></a>
-
-```typescript
-public readonly enableRule: boolean;
-```
-
-- *Type:* boolean
-
-Whether the EventBridge rules are enabled.
-
-Defaults to true if omitted.
-
----
-
 ### Secrets <a name="Secrets" id="rds-database-auto-start-preventer.Secrets"></a>
 
 External secrets for notifications (e.g. Slack). Omit {@link Secrets.slackSecretName} to skip Slack notifications.

package/README.md

@@ -12,22 +12,32 @@ CDK construct library that stops RDS DB instances and clusters after they are au
 ## Features
 
 - **EventBridge integration** – Listens for RDS DB Instance (RDS-EVENT-0154) and DB Cluster (RDS-EVENT-0153) auto-start events
-- **Handler-side tag filtering** – EventBridge rules match all auto-start events; the Lambda evaluates `TagList` from `rds:DescribeDBInstances` / `rds:DescribeDBClusters` and skips resources that do not match `tagKey` / `tagValues`
-- **Durable Lambda** – Uses AWS Lambda Durable Execution for reliable, long-running workflow (initial wait, status wait, stop, and post-stop wait)
-- **Least-privilege IAM** – Grants RDS describe and stop actions only (no Resource Groups Tagging API)
+- **Handler-side tag filtering** – EventBridge rules match all auto-start events; the Lambda evaluates `TagList` from `rds:DescribeDBInstances` / `rds:DescribeDBClusters`. Tag mismatch is a no-op (no StopDB*, no Slack)
+- **Durable Lambda** – Uses AWS Lambda Durable Execution for a long-running workflow (initial wait, status wait, stop, and post-stop wait) with a 2-hour execution timeout
+- **Least-privilege IAM** – Describe is scoped to account/region `db` / `cluster` ARNs; Stop is further limited by `aws:ResourceTag` matching `tagKey` / `tagValues` (no Resource Groups Tagging API)
 - **Slack notifications** – When `slackSecretName` is set, sends a message when this invocation called `StopDBInstance` / `StopDBCluster` and the resource reached `stopped` (no notification when the secret name is omitted, the resource was already stopped, or tags did not match)
 - **Optional rule toggle** – EventBridge rules can be enabled or disabled via `enableRule`
 
 ## How it works
 
 1. EventBridge invokes the Durable Lambda with the RDS auto-start event and tag filter parameters (`tagKey`, `tagValues`).
-2. The handler waits 1 minute, then waits on DescribeDB* until the resource leaves transitional statuses.
-3. If the resource tag does not match, the handler exits with no stop action.
-4. If the resource is `available` and tags match, the handler calls StopDB* and waits until `stopped`.
+2. The handler waits **1 minute**, then calls DescribeDB* until the resource leaves transitional statuses. While the status stays transitional (or stopping after StopDB*), it waits up to **5 minutes** between describes.
+3. If the resource tag does not match, the handler exits as a **no-op** (no StopDB*, no Slack).
+4. If the resource is `available` and tags match, the handler calls StopDB* and waits until `stopped` (again using up to 5-minute intervals while transitional).
 5. If the resource is already `stopped` (for example, stopped by another process), the handler exits without calling StopDB* and without posting to Slack.
 6. When `slackSecretName` is set, Slack is notified only when StopDB* was invoked by this invocation and the resource reached `stopped`. When it is omitted, the handler does not post to Slack.
 
-Tag the RDS instances or clusters you want to protect (for example, `AutoStartPrevent=YES`). Resources without a matching tag are left running.
+Timing defaults (not configurable via props today):
+
+| Setting | Value |
+|---------|-------|
+| Initial wait before the first describe | 1 minute |
+| Wait between describes while status is transitional / stopping | up to 5 minutes |
+| Lambda invocation `timeout` | 15 minutes |
+| Durable `executionTimeout` | 2 hours |
+| Durable history `retentionPeriod` | 1 day |
+
+Tag the RDS instances or clusters you want to protect (for example, `AutoStartPrevent=YES`). Resources without a matching tag are left running (no-op).
 
 ## Installation
 
@@ -51,55 +61,71 @@ pnpm add rds-database-auto-start-preventer
 
 ## Usage
 
-Use `RDSDatabaseAutoStartPreventer` when you want to add auto-start prevention to an existing stack or compose it with other constructs. Omit `slackSecretName` to stop matching resources without Slack.
+### Minimal deployable app
+
+Use `RDSDatabaseAutoStartPreventStack` when you want a dedicated stack you can deploy as-is. Put this in your CDK app entry (for example `bin/app.ts`), then deploy.
 
 ```typescript
-import { App, Stack } from 'aws-cdk-lib';
-import { RDSDatabaseAutoStartPreventer } from 'rds-database-auto-start-preventer';
+import { App } from 'aws-cdk-lib';
+import { RDSDatabaseAutoStartPreventStack } from 'rds-database-auto-start-preventer';
 
 const app = new App();
-const stack = new Stack(app, 'MyStack');
 
-new RDSDatabaseAutoStartPreventer(stack, 'RDSDatabaseAutoStartPreventer', {
+new RDSDatabaseAutoStartPreventStack(app, 'RDSDatabaseAutoStartPreventStack', {
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION,
+  },
+  stackName: 'rds-database-auto-start-prevent',
   targetResource: {
     tagKey: 'AutoStartPrevent',
     tagValues: ['YES'],
   },
-  secrets: {},
+  // Omit slackSecretName to skip Slack; set it when stop should notify Slack.
+  secrets: {
+    slackSecretName: 'my-app/slack',
+  },
 });
+
+app.synth();
 ```
 
-Pass `slackSecretName` when a successful stop should post to Slack. `enableRule` defaults to `true`.
+Deploy checklist:
+
+1. Install this package and peers (`aws-cdk-lib`, `constructs`) in your CDK app.
+2. Tag the RDS instances or clusters to protect (for example `AutoStartPrevent=YES`).
+3. Optional: create the Secrets Manager secret described in [Slack secret](#slack-secret-aws-secrets-manager). Omit `slackSecretName` if you do not need Slack.
+4. From the CDK app: `npx cdk deploy RDSDatabaseAutoStartPreventStack`
+
+### Construct in an existing stack
+
+Use `RDSDatabaseAutoStartPreventer` when you want to add auto-start prevention to an existing stack or compose it with other constructs. Omit `slackSecretName` to stop matching resources without Slack.
 
 ```typescript
+import { App, Stack } from 'aws-cdk-lib';
+import { RDSDatabaseAutoStartPreventer } from 'rds-database-auto-start-preventer';
+
+const app = new App();
+const stack = new Stack(app, 'MyStack');
+
 new RDSDatabaseAutoStartPreventer(stack, 'RDSDatabaseAutoStartPreventer', {
   targetResource: {
     tagKey: 'AutoStartPrevent',
     tagValues: ['YES'],
   },
-  enableRule: true,
-  secrets: {
-    slackSecretName: 'my-app/slack',
-  },
+  secrets: {},
 });
 ```
 
-### Stack
-
-Use `RDSDatabaseAutoStartPreventStack` when you want a dedicated stack that only deploys the RDS auto-start prevent resources.
+Pass `slackSecretName` when a successful stop should post to Slack. `enableRule` defaults to `true`.
 
 ```typescript
-import { App } from 'aws-cdk-lib';
-import { RDSDatabaseAutoStartPreventStack } from 'rds-database-auto-start-preventer';
-
-const app = new App();
-
-new RDSDatabaseAutoStartPreventStack(app, 'RDSDatabaseAutoStartPreventStack', {
-  stackName: 'rds-database-auto-start-prevent',
+new RDSDatabaseAutoStartPreventer(stack, 'RDSDatabaseAutoStartPreventer', {
   targetResource: {
     tagKey: 'AutoStartPrevent',
     tagValues: ['YES'],
   },
+  enableRule: true,
   secrets: {
     slackSecretName: 'my-app/slack',
   },
@@ -108,6 +134,8 @@ new RDSDatabaseAutoStartPreventStack(app, 'RDSDatabaseAutoStartPreventStack', {
 
 ### Slack secret (AWS Secrets Manager)
 
+Create the secret **before** deploy when you want Slack notifications. Omit `slackSecretName` to skip Slack entirely (no secret and no Secrets Manager IAM are required in that case).
+
 Store a JSON object in AWS Secrets Manager with the Slack Bot Token and channel ID:
 
 | Key | Value |
@@ -124,6 +152,8 @@ Example secret value:
 }
 ```
 
+When `slackSecretName` is set, the construct grants the Lambda role read access to that secret and attaches the AWS Parameters and Secrets Extension. You do not need to add a separate Secrets Manager policy yourself for this secret.
+
 ## Options
 
 | Option | Type | Required | Description |
@@ -148,6 +178,18 @@ See [API.md](./API.md).
 - **constructs** ^10.5.1
 - **AWS Lambda** runtime Node.js 24.x with Durable Execution (deployed by the construct)
 
+## Notes
+
+- **Aurora / dual events:** An Aurora auto-start can emit both a DB cluster event (`RDS-EVENT-0153`) and DB instance event(s) (`RDS-EVENT-0154`). This package listens for both and may run separate Durable executions. Tag mismatch remains a no-op; if the resource is already `stopped`, the handler does not call StopDB* and does not post to Slack.
+- **IAM:** RDS Describe is limited to account/region `db` / `cluster` ARNs. Stop requires a matching `aws:ResourceTag` for your `tagKey` / `tagValues`. Slack secret read is granted only when `slackSecretName` is set.
+
+## Troubleshooting
+
+- **CloudWatch Logs:** The construct creates a dedicated Log Group for the Durable Lambda (JSON logs, 3-month retention). After a successful create, the log group uses `RetainExceptOnCreate` so it remains available for incident review after stack delete or replace.
+- **Nothing stopped / no Slack:** Confirm the resource tag matches `tagKey` / `tagValues`. Mismatch is intentional no-op with no Slack message.
+- **Stop attempted but Slack missing:** Slack runs only when this invocation called StopDB* and the resource reached `stopped`, and only when `slackSecretName` is set. Already-stopped resources skip Slack.
+- **Secret errors:** Ensure the secret exists before deploy, JSON has non-empty `token` and `channel`, and the name passed as `slackSecretName` matches Secrets Manager.
+
 ## License
 
 This project is licensed under the Apache-2.0 License.

package/assets/funcs/auto-start-prevent.lambda/index.js

@@ -25080,7 +25080,7 @@ var import_web_api = __toESM(require_dist5());
 var import_aws_lambda_secret_fetcher = __toESM(require_lib4());
 var import_strict_env_resolver = __toESM(require_lib2());
 
-// src/funcs/auto-start-prevent.predicates.ts
+// src/funcs/core/auto-start-prevent.predicates.ts
 var WAIT_INTERVAL_MINUTES = 5;
 var TRANSITIONAL_STATUSES = /* @__PURE__ */ new Set([
   "starting",