# 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 (HIPAA §164.312(a)(2)(iv), 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.yaml`](examples/simple.yaml)
```yaml
# Simple CloudFront distribution (S3 origin, no WAF)
uses: acdl/pipelines/deploy.yaml@v1.6
module: cloudfront
environment: dev
inputs:
  bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com
  region: us-east-1
```

### Complex

A production deployment with optional inputs:

[`examples/complex.yaml`](examples/complex.yaml)
```yaml
# Complex CloudFront with WAF + custom TTL + viewer protocol redirect
uses: acdl/pipelines/deploy.yaml@v1.6
module: cloudfront
environment: dev
inputs:
  bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com
  price_class: PriceClass_100
  viewer_protocol_policy: redirect-to-https
  default_ttl: 3600
  max_ttl: 86400
  waf_web_acl_arn: arn:aws:wafv2:us-east-1:000000000000:webacl/my-waf
  region: us-east-1
```

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