# kms-key — KMS customer-managed key

> **Module kind:** primitive  |  **Version:** 1.0.0

A customer-managed KMS key for per-stack encryption. Created with key
rotation enabled. One key per L2 deployment (no shared keys).

## Resources

| Resource | Type | Purpose |
|----------|------|---------|
| kms-key | `aws_kms_key` | The KMS customer-managed key |

## Inputs

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `description` | string | yes | — | Description of the KMS key |
| `region` | string | yes | — | AWS region the KMS key is created in |
| `deletion_window_days` | number | no | 30 | Number of days before the key is deleted after deletion is requested |

## Outputs

| Name | Type | Description |
|------|------|-------------|
| `kms_key_arn` | arn | The ARN of the KMS key |
| `kms_key_id` | string | The ID of the KMS key |

## NFRs

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `enable_rotation` | boolean | true | Enable automatic key rotation |
| `deletion_protection` | boolean | true | Prevent key destruction |
| `encryption_enabled` | boolean | true | Encryption is always enabled for a KMS key |

## Usage

```json
{
  "id": "kms-key",
  "type": "aws:kms:key",
  "module": "kms-key@1.0.0",
  "inputs": {
    "description": "ACDL per-stack CMK",
    "region": "us-east-1"
  }
}
```

A concrete instance is at `instance.json` (used by the platform
pipeline as the regression baseline).

## Compliance extension points

- **Key rotation** — automatic key rotation enabled by default (SOC2 CC6.1, GDPR Art.32).
- **Deletion protection** — pending deletion window prevents accidental destruction (SOC2 CC7.2).
- **Key policy** — restrict key usage to the stack's IAM roles (SOC2 CC6.1, GDPR Art.32).
- **Audit logging** — CloudTrail logs all KMS API calls (SOC2 CC7.2, DORA audit trail).

## Examples

Validated example contracts are in [`examples/`](examples/). The platform-test
pipeline validates them against `schemas/contract.schema.json`.

### Simple

A minimal deployment:

[`examples/simple.yaml`](examples/simple.yaml)
```yaml
uses: acdl/pipelines/deploy.yaml@v1.8
module: kms-key
environment: dev
inputs:
  description: "Simple CMK for testing"
  region: us-east-1
```

### Complex

A production deployment with optional inputs:

[`examples/complex.yaml`](examples/complex.yaml)
```yaml
uses: acdl/pipelines/deploy.yaml@v1.8
module: kms-key
environment: dev
inputs:
  description: "Production CMK with 90-day deletion window"
  region: us-east-1
  deletion_window_days: 90
```

## Versioning

`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
require a new registry entry (immutable publication); old entries enter
a 12-month deprecation window.