@composurecdk/logs 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @composurecdk/logs
+
+CloudWatch Logs builders for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for CloudWatch log groups with secure, AWS-recommended defaults. It wraps the CDK [LogGroup](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroup.html) construct — refer to the CDK documentation for the full set of configurable properties.
+
+## Log Group Builder
+
+```ts
+import { createLogGroupBuilder } from "@composurecdk/logs";
+
+const logGroup = createLogGroupBuilder().logGroupName("/my-app/api").build(stack, "ApiLogs");
+```
+
+Every [LogGroupProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroupProps.html) property is available as a fluent setter on the builder.
+
+## Secure Defaults
+
+`createLogGroupBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property        | Default     | Rationale                                                                       |
+| --------------- | ----------- | ------------------------------------------------------------------------------- |
+| `retention`     | `TWO_YEARS` | Prevents unbounded log accumulation while preserving a meaningful audit window. |
+| `removalPolicy` | `RETAIN`    | Logs are audit records that should survive infrastructure teardown.             |
+
+These defaults are guided by the [AWS Well-Architected Security Pillar — SEC04-BP01](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html).
+
+The defaults are exported as `LOG_GROUP_DEFAULTS` for visibility and testing:
+
+```ts
+import { LOG_GROUP_DEFAULTS } from "@composurecdk/logs";
+```
+
+### Overriding defaults
+
+```ts
+import { RemovalPolicy } from "aws-cdk-lib";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+
+const logGroup = createLogGroupBuilder()
+  .retention(RetentionDays.SIX_MONTHS)
+  .removalPolicy(RemovalPolicy.DESTROY)
+  .build(stack, "EphemeralLogs");
+```
+
+### Encryption
+
+CloudWatch Logs encrypts all log data at rest using AWS-managed keys. For additional control (key rotation, CloudTrail audit, access revocation), provide a customer-managed KMS key:
+
+```ts
+const logGroup = createLogGroupBuilder().encryptionKey(myKmsKey).build(stack, "EncryptedLogs");
+```

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import { type LogGroupProps } from "aws-cdk-lib/aws-logs";
+/**
+ * Secure, AWS-recommended defaults applied to every log group built with
+ * {@link createLogGroupBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ */
+export declare const LOG_GROUP_DEFAULTS: Partial<LogGroupProps>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAC,aAAa,CAerD,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,23 @@
+import { RemovalPolicy } from "aws-cdk-lib";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+/**
+ * Secure, AWS-recommended defaults applied to every log group built with
+ * {@link createLogGroupBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ */
+export const LOG_GROUP_DEFAULTS = {
+    /**
+     * Retain logs for two years. CloudWatch defaults to indefinite retention;
+     * an explicit policy prevents unbounded log accumulation while preserving
+     * a meaningful audit window.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     */
+    retention: RetentionDays.TWO_YEARS,
+    /**
+     * Retain the log group when the stack is deleted. Logs are operational
+     * and audit records that should survive infrastructure teardown.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     */
+    removalPolicy: RemovalPolicy.RETAIN,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAsB,MAAM,sBAAsB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD;;;;;OAKG;IACH,SAAS,EAAE,aAAa,CAAC,SAAS;IAElC;;;;OAIG;IACH,aAAa,EAAE,aAAa,CAAC,MAAM;CACpC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createLogGroupBuilder, type LogGroupBuilderResult, type ILogGroupBuilder, } from "./log-group-builder.js";
+export { LOG_GROUP_DEFAULTS } from "./defaults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createLogGroupBuilder, } from "./log-group-builder.js";
+export { LOG_GROUP_DEFAULTS } from "./defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAGtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/log-group-builder.d.ts

@@ -0,0 +1,62 @@
+import { LogGroup, type LogGroupProps } from "aws-cdk-lib/aws-logs";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+type LogGroupBuilderProps = LogGroupProps;
+/**
+ * The build output of a {@link ILogGroupBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface LogGroupBuilderResult {
+    /** The CloudWatch log group construct created by the builder. */
+    logGroup: LogGroup;
+}
+/**
+ * A fluent builder for configuring and creating a CloudWatch log group.
+ *
+ * Each configuration property from the CDK {@link LogGroupProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * a log group with the configured properties and returns a
+ * {@link LogGroupBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const logs = createLogGroupBuilder()
+ *   .retention(RetentionDays.SIX_MONTHS);
+ * ```
+ */
+export type ILogGroupBuilder = IBuilder<LogGroupBuilderProps, LogGroupBuilder>;
+declare class LogGroupBuilder implements Lifecycle<LogGroupBuilderResult> {
+    props: Partial<LogGroupBuilderProps>;
+    build(scope: IConstruct, id: string): LogGroupBuilderResult;
+}
+/**
+ * Creates a new {@link ILogGroupBuilder} for configuring a CloudWatch log group.
+ *
+ * This is the entry point for defining a log group component. The returned
+ * builder exposes every {@link LogGroupProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for a CloudWatch log group.
+ *
+ * @example
+ * ```ts
+ * const logs = createLogGroupBuilder()
+ *   .retention(RetentionDays.SIX_MONTHS);
+ *
+ * // Use standalone:
+ * const result = logs.build(stack, "MyLogGroup");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { logs, api: createRestApiBuilder() },
+ *   { logs: [], api: ["logs"] },
+ * );
+ * ```
+ */
+export declare function createLogGroupBuilder(): ILogGroupBuilder;
+export {};
+//# sourceMappingURL=log-group-builder.d.ts.map

package/dist/log-group-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-group-builder.d.ts","sourceRoot":"","sources":["../src/log-group-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG5E,KAAK,oBAAoB,GAAG,aAAa,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAE/E,cAAM,eAAgB,YAAW,SAAS,CAAC,qBAAqB,CAAC;IAC/D,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAM;IAE1C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,qBAAqB;CAS5D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD"}

package/dist/log-group-builder.js

@@ -0,0 +1,43 @@
+import { LogGroup } from "aws-cdk-lib/aws-logs";
+import { Builder } from "@composurecdk/core";
+import { LOG_GROUP_DEFAULTS } from "./defaults.js";
+class LogGroupBuilder {
+    props = {};
+    build(scope, id) {
+        const mergedProps = {
+            ...LOG_GROUP_DEFAULTS,
+            ...this.props,
+        };
+        return {
+            logGroup: new LogGroup(scope, id, mergedProps),
+        };
+    }
+}
+/**
+ * Creates a new {@link ILogGroupBuilder} for configuring a CloudWatch log group.
+ *
+ * This is the entry point for defining a log group component. The returned
+ * builder exposes every {@link LogGroupProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for a CloudWatch log group.
+ *
+ * @example
+ * ```ts
+ * const logs = createLogGroupBuilder()
+ *   .retention(RetentionDays.SIX_MONTHS);
+ *
+ * // Use standalone:
+ * const result = logs.build(stack, "MyLogGroup");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { logs, api: createRestApiBuilder() },
+ *   { logs: [], api: ["logs"] },
+ * );
+ * ```
+ */
+export function createLogGroupBuilder() {
+    return Builder(LogGroupBuilder);
+}
+//# sourceMappingURL=log-group-builder.js.map

package/dist/log-group-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-group-builder.js","sourceRoot":"","sources":["../src/log-group-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAsB,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAiCnD,MAAM,eAAe;IACnB,KAAK,GAAkC,EAAE,CAAC;IAE1C,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,WAAW,GAAG;YAClB,GAAG,kBAAkB;YACrB,GAAG,IAAI,CAAC,KAAK;SACU,CAAC;QAC1B,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;SAC/C,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,OAAO,CAAwC,eAAe,CAAC,CAAC;AACzE,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@composurecdk/logs",
+  "version": "0.1.0",
+  "description": "Composable CloudWatch log group builder with secure defaults",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/core": "^0.1.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "aws-cdk-lib": "^2.245.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}