# cloudfront — CloudFront distribution

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

A CloudFront distribution with an S3 origin via Origin Access Control
(OAC). The distribution serves the bucket's static content from the
global edge network with HTTPS redirection by default. An optional WAF
web ACL can be associated to filter traffic before it reaches the
origin.

## Resources

| Resource | Type | Purpose |
|----------|------|---------|
| `oac` | `aws_cloudfront_origin_access_control` | Origin Access Control signing the S3 origin |
| `distribution` | `aws_cloudfront_distribution` | The CloudFront distribution with an S3 origin via OAC |

## Inputs

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `bucket_regional_domain_name` | string | yes | — | The S3 bucket regional domain name (ref to s3 origin) |
| `price_class` | string | no | `PriceClass_100` | CloudFront price class |
| `viewer_protocol_policy` | string | no | `redirect-to-https` | Viewer protocol policy |
| `default_ttl` | number | no | 3600 | Default TTL in seconds |
| `max_ttl` | number | no | 86400 | Max TTL in seconds |
| `waf_web_acl_arn` | string | no | — | WAF web ACL ARN to associate (ref to waf) |
| `region` | string | yes | — | AWS region (CloudFront is global but the provider region is used for the OAC) |

## Outputs

| Name | Type | Description |
|------|------|-------------|
| `distribution_arn` | arn | The CloudFront distribution ARN |
| `distribution_domain_name` | string | The CloudFront distribution domain name (e.g. d111111abcdef8.cloudfront.net) |
| `oac_id` | string | The Origin Access Control ID |

## Usage

```json
{
  "id": "cloudfront",
  "type": "aws:cloudfront:distribution",
  "module": "cloudfront@1.0.0",
  "inputs": {
    "bucket_regional_domain_name": "ref:s3.bucket_regional_domain_name",
    "price_class": "PriceClass_100",
    "viewer_protocol_policy": "redirect-to-https",
    "default_ttl": 3600,
    "max_ttl": 86400,
    "waf_web_acl_arn": "ref:waf.web_acl_arn",
    "region": "us-east-1"
  }
}
```

The `bucket_regional_domain_name` and `waf_web_acl_arn` inputs are
typically wired as `ref:` expressions from the `s3` and `waf` primitives
inside a module composition (see `modules/l2/static-assets`).

## Compliance extension points

- **TLS/HTTPS** — viewer protocol policy defaults to `redirect-to-https`;
  a custom ACM certificate + `viewer_certificate` block can pin TLS to a
  customer domain (SOC2 CC6.1, GDPR Art.32).
- **Geo restriction** — the `restrictions.geo_restriction` block can
  whitelist/blacklist countries for data-residency compliance (GDPR
  Art.44, SOC2 CC6.1).
- **Logging** — CloudFront access logs to an S3 bucket for auditability
  (SOC2 CC7.2, DORA audit trail).
- **Field-level encryption** — add field-level encryption for PII fields
  in POST bodies (GDPR Art.32).

## 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.yml`](examples/simple.yml)
```yaml
environment: dev
id: cdn
infrastructure:
  cloudfront:
    inputs:
      bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com
      region: us-east-1
    version: 1.0.0
name: cloudfront
```

### Complex

A production deployment with optional inputs:

[`examples/complex.yml`](examples/complex.yml)
```yaml
environment: dev
id: cdn
infrastructure:
  cloudfront:
    inputs:
      bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com
      default_ttl: 3600
      max_ttl: 86400
      price_class: PriceClass_100
      region: us-east-1
      viewer_protocol_policy: redirect-to-https
      waf_web_acl_arn: arn:aws:wafv2:us-east-1:000000000000:webacl/my-waf
    version: 1.0.0
name: cloudfront
```

## 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.