npm package: @phila/cdk-s3
Description: City of Philadelphia s3 bucket CDK constructs.
Latest version: 0.0.1

# S3 CDK Construct Library

City of Philadelphia s3 bucket CDK constructs.

## Overview

This CDK construct library provides reusable AWS S3 bucket constructs for different use cases: web hosting files, log storage, and general file storage. Each construct is configured with appropriate security settings, encryption, and lifecycle management.

## Installation

```bash
npm install @phila/cdk-s3
```

## Bucket Types

### WebfilesBucket

Creates an S3 bucket for static website files which must be served via CloudFront. _Do not use for protected and private files, just public website ones._ This bucket is configured with:

- S3-managed encryption (no KMS)
- No lifecycle rules
- Fully private. (Must use AOC in CloudFront for serving)
- SSL enforcement
- No versioning
- Automatic cleanup in non-production environments

**Props:**

- `GlobalProps` (required) - See [GlobalProps documentation](../_shared/README.md#globalprops)
- `logBucket?: IBucket` (optional) - Optional log bucket for access logging. Provide an instance of [LogBucket](#logbucket).

**Usage:**

```typescript
import { Compliance, Confidentiality, WebfilesBucket } from "@phila/cdk-s3";

const webfilesBucket = new WebfilesBucket(stack, "WebfilesBucket", {
  project: "my-project",
  environment: "production",
  department: "4-oit",
  team: "Platform Engineering",
  contact: "team@phila.gov",
  compliance: Compliance.STANDARD,
  confidentiality: Confidentiality.LOW,
  tags: {
    Example: "Example tag",
  },
  logBucket: logBucket.bucket, // optional
});
```

### LogBucket

Creates an S3 bucket for centralized S3 access logs. This bucket is configured with:

- KMS encryption
- Configurable log retention (default: 30 days)
- Fully private with SSL enforcement
- No versioning
- Automatic cleanup enabled

**Props:**

- `GlobalProps` (required) - See [GlobalProps documentation](../_shared/README.md#globalprops)
- `logRetentionDays?: number` (optional) - Log retention days (default: 30).
- `logBucket?: IBucket` (optional) - Optional log bucket for access logging (typically not used for log buckets themselves because it may create a cycle loop)

**Usage:**

```typescript
import { Compliance, Confidentiality, LogBucket } from "@phila/cdk-s3";

const logBucket = new LogBucket(stack, "LogBucket", {
  project: "my-project",
  environment: "production",
  department: "4-oit",
  team: "Platform Engineering",
  contact: "team@phila.gov",
  compliance: Compliance.STANDARD,
  confidentiality: Confidentiality.LOW,
  tags: {
    Example: "Example tag",
  },
  logRetentionDays: 90, // optional, default is 30
});
```

### FilesBucket

Creates an S3 bucket for application file storage. This bucket is configured with:

- KMS encryption
- Optional Glacier transition for cost optimization
- Fully private (all public access blocked), access must be granted via IAM policies. (e.g. Fargate task role to Read and Write application files in the bucket)
- Optional versioning (default: false)
- SSL enforcement
- Automatic cleanup in non-production environments

**Props:**

- `GlobalProps` (required) - See [GlobalProps documentation](../_shared/README.md#globalprops)
- `glacierTransitionDays?: number` (optional) - Days before transitioning files to Glacier (default: 60). Set to 0 to disable Glacier transition.
- `versioned?: boolean` (optional) - Enable versioning on the bucket (default: false)
- `logBucket?: IBucket` (optional) - Optional log bucket for access logging

**Usage:**

```typescript
import { Compliance, Confidentiality, FilesBucket } from "@phila/cdk-s3";

const filesBucket = new FilesBucket(stack, "FilesBucket", {
  project: "my-project",
  environment: "production",
  department: "4-oit",
  team: "Platform Engineering",
  contact: "team@phila.gov",
  compliance: Compliance.STANDARD,
  confidentiality: Confidentiality.MEDIUM,
  tags: {
    Example: "Example tag",
  },
  glacierTransitionDays: 90, // optional, default is 60, set to 0 to disable
  versioned: true, // optional, default is false
  logBucket: logBucket.bucket, // optional
});
```

## GlobalProps

All bucket constructs require `GlobalProps`. For complete documentation on `GlobalProps`, including all properties, enums, and usage examples, see the [Shared CDK Construct Library documentation](../_shared/README.md#globalprops).

## Features

- **Security**: All buckets are fully private with SSL enforcement
- **Encryption**: KMS encryption for log and files buckets, S3-managed for web files
- **Lifecycle Management**: Configurable retention and Glacier transitions
- **CDK Outputs**: Exposes bucket names as CloudFormation outputs
- **Compliance**: NIST 800-53 Rev 5 compliant with appropriate CDK Nag suppressions

## Development

### Prerequisites

- Node.js 22+
- pnpm
- AWS CDK CLI

### Commands

- `pnpm run build` - Build the library
- `pnpm run watch` - Build in watch mode
- `pnpm run test` - Run tests
- `pnpm run lint` - Lint code
- `pnpm run format` - Format code