docs/storage/s3-setup.md

# S3 Storage Setup

This app supports S3 for file uploads (dev/prod). Development can rely on presigned PUTs directly from the browser, while production should keep the bucket private and serve via CDN (CloudFront + Origin Access Control) or signed GET URLs.

## Buckets
- Pick a region (e.g., `us-east-2`)
  - Dev/Test example: `better-chatbot-dev` (public GET on `uploads/` only if needed)
  - Prod example: `better-chatbot-prod` (private)
- Enable default encryption (SSE-S3) and versioning on both buckets.

## CORS
- Dev bucket: allow PUT/GET/HEAD from the origins you use locally and in staging, for example:
  - `http://localhost:3000`, `http://127.0.0.1:3000`
  - `https://staging.your-domain.com`, `http://staging.your-domain.com`
- Prod bucket: allow GET/HEAD only from your production domain (e.g., `https://app.your-domain.com`). Avoid enabling browser PUT in production.

## Dev public-read policy (prefix-only)
Grant public GET for the `uploads/` prefix on the dev bucket only if you need unauthenticated downloads:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPublicReadForUploadsPrefix",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::better-chatbot-dev/uploads/*"
    }
  ]
}
```

## IAM (app runtime)
Least privilege for app role/user:
- Actions: `s3:PutObject`, `s3:GetObject`, `s3:DeleteObject`, `s3:HeadObject`
- Resources: `arn:aws:s3:::<bucket-name>/uploads/*`

## Env configuration
- Dev/local:
  - `FILE_STORAGE_TYPE=s3`
  - `FILE_STORAGE_PREFIX=uploads`
  - `FILE_STORAGE_S3_BUCKET=better-chatbot-dev`
  - `FILE_STORAGE_S3_REGION=us-east-2` (or set `AWS_REGION`)
  - Use AWS SSO/profile or `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`
- Prod:
  - `FILE_STORAGE_S3_BUCKET=better-chatbot-prod`
  - Prefer CloudFront; set `FILE_STORAGE_S3_PUBLIC_BASE_URL=https://<cdn-domain>`

## Verify locally
- Ensure `aws sso login --profile <your_profile>` (or credentials are already available).
- Test presign script:
```
AWS_PROFILE=<your_profile> \
FILE_STORAGE_TYPE=s3 \
FILE_STORAGE_S3_BUCKET=better-chatbot-dev \
FILE_STORAGE_S3_REGION=us-east-2 \
pnpm tsx scripts/verify-s3-upload-url.ts
```
- You should get `{ directUploadSupported: true, url, key, method: PUT }`.
- Upload with curl (optional): `curl -X PUT -H "Content-Type: image/png" --data-binary @file.png "<url>"`.