build(deps): bump terraform-linters/setup-tflint from 4 to 6

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
           pip install black flake8
 
       - name: Setup Terraform
-        uses: hashicorp/setup-terraform@v3
+        uses: hashicorp/setup-terraform@v4
         with:
           terraform_version: 1.5.7
 
@@ -37,6 +37,22 @@ jobs:
       - name: Terraform validate
         run: terraform -chdir=infra/environments/dev validate
 
+
+      - name: Setup tflint
+        uses: terraform-linters/setup-tflint@v6
+
+      - name: tflint
+        run: |
+          cd infra
+          tflint --init
+          tflint --recursive --minimum-failure-severity=error
+
+      - name: tfsec
+        uses: aquasecurity/tfsec-action@v1.0.3
+        with:
+          working_directory: infra
+          additional_args: --minimum-severity HIGH
+
       - name: Secrets and hygiene check
         run: sh scripts/security/check_secrets.sh
 

README.md

@@ -1,7 +1,21 @@
 # SecureDocs AWS
 
+[![CI](https://github.com/giselleevita/secure-docs-aws/actions/workflows/ci.yml/badge.svg)](https://github.com/giselleevita/secure-docs-aws/actions/workflows/ci.yml)
+
 _A security-focused document storage service on AWS that teaches IAM, S3, KMS, CloudTrail, and ownership-enforcement patterns._
 
+```mermaid
+flowchart LR
+  U["Client"] -->|"JWT"| APIGW["API Gateway<br/>(Cognito JWT authorizer)"]
+  APIGW --> UP["Lambda: upload"]
+  APIGW --> LS["Lambda: list"]
+  APIGW --> DL["Lambda: download"]
+  APIGW --> DEL["Lambda: delete"]
+  UP & LS & DL & DEL -->|"owner_id check"| DDB[("DynamoDB<br/>metadata")]
+  UP & DL & DEL -->|"presigned URL (5 min)"| S3[("S3<br/>private + SSE-KMS + versioned")]
+  APIGW & UP & LS & DL & DEL -->|"logs"| CT["CloudTrail + CloudWatch Logs"]
+```
+
 ## Overview
 
 SecureDocs AWS is a serverless document service where authenticated users can upload, list, download, and delete only their own files. The project is deliberately small, but it exercises the core security controls that matter in a multi-user cloud system.

docs/architecture/overview.md

@@ -0,0 +1,35 @@
+# System Overview
+
+SecureDocs AWS is a serverless, single-tenant-per-user document store. Every
+request is authenticated and every object access is authorized against the
+caller's identity before any data is returned.
+
+## Request flow
+
+1. **Authenticate** — the client presents a Cognito-issued JWT. API Gateway's
+   JWT authorizer validates it before any Lambda runs.
+2. **Route** — API Gateway dispatches to one of four purpose-built Lambdas:
+   `upload`, `list`, `download`, `delete`. Each has its own IAM role scoped to
+   only the actions it needs.
+3. **Authorize ownership** — the Lambda looks up file metadata in DynamoDB
+   keyed by `owner_id` + `object_key`, and refuses (403) any access to an object
+   the caller does not own.
+4. **Access storage** — instead of proxying bytes or handing out S3 credentials,
+   the Lambda returns a short-lived (5-minute) presigned URL. The bucket blocks
+   public access, encrypts at rest with SSE-KMS, and keeps object versions.
+5. **Audit** — API Gateway, Lambda, and S3 activity is captured by CloudTrail
+   and CloudWatch Logs.
+
+## Components
+
+| Component | Role |
+|---|---|
+| Cognito | User identity and JWT issuance |
+| API Gateway | JWT authorizer, routing |
+| Lambda (×4) | Per-operation handlers, least-privilege IAM roles |
+| DynamoDB | Ownership metadata (`owner_id`, `object_key`) |
+| S3 | Encrypted, private, versioned object storage |
+| KMS | Encryption keys for S3 objects |
+| CloudTrail + CloudWatch | Audit trail |
+
+See [decisions.md](./decisions.md) for the security rationale behind each choice.

infra/environments/dev/observability.tf

@@ -114,6 +114,7 @@ resource "aws_kms_key_policy" "cloudtrail" {
 resource "aws_cloudtrail" "secure_docs" {
   name                          = "secure-docs-trail"
   s3_bucket_name                = module.storage.bucket_name
+  kms_key_id                    = module.storage.kms_key_arn
   enable_log_file_validation    = true
   include_global_service_events = true
   is_multi_region_trail         = true