@auth-craft/aws-cf-stack 1.7.1 → 1.9.0

package/.env.example

@@ -11,12 +11,20 @@
 # Required vs optional is marked per line.
 
 # ─── Stage / project / naming ────────────────────────────────────────────────
+# Resources are named {app}-{env}-{layer}-{component}, e.g. snapshot-commerce-prod-auth-data.
+#   app       = AUTH_CRAFT_APP_NAME, else auth-craft[-<project>]
+#   env       = STAGE
+#   layer     = LAYER (default "auth")
+#   component = per-resource: data (table), api (Lambda), system/tenant/customer (workers)
+# The {app}-{env}-{layer} base (no component) is also AUTH_SYSTEM_NAME / the JWT issuer.
 STAGE=dev                     # optional (flag --stage), default dev | staging | prod
                               #   also accepts production -> prod, development -> dev
-PROJECT=default               # optional (flag --project), default "default" (multi-tenant naming)
-AUTH_CRAFT_APP_NAME=          # optional (flag --app-name) — override the app/resource name
-                              #   (e.g. snapshot-auth). Unset = auth-craft[-<project>]. Drives
-                              #   stack names, table, Lambda fn, worker names.
+PROJECT=default               # optional (flag --project), default "default". app = auth-craft-<project>
+AUTH_CRAFT_APP_NAME=          # optional (flag --app-name) — full rebrand of the app name
+                              #   (e.g. snapshot-commerce, drops the auth-craft prefix).
+                              #   Unset = auth-craft[-<project>].
+LAYER=auth                    # optional (flag --layer), default "auth" — layer namespace within
+                              #   the app; use a larger app's other layers (e.g. billing) per deploy.
 
 # ─── Tool command overrides (optional — pin your own binaries) ───────────────
 AUTH_CRAFT_WRANGLER_CMD=      # optional — e.g. "pnpm wrangler"; default "npx --yes wrangler"
@@ -147,6 +155,18 @@ LAMBDA_REFRESH_COOKIE_TENANT=refresh_token_tenant
 LAMBDA_REFRESH_COOKIE_SYSTEM=refresh_token_system
 LAMBDA_AUDIT_ENABLED=false
 LAMBDA_DEVICE_TRACKING=true
+
+# ─── Observability cost controls (optional) ──────────────────────────────────
+# CloudWatch Logs are billed for ingestion AND stored volume; retention only affects
+# storage. Short retention in dev is the cheap default.
+#   Unset  → 3 days in dev, 30 days in staging/prod.
+#   Valid  → 1,3,5,7,14,30,60,90,120,150,180,365,400,545,731,1096,1827,2192,2557,
+#            2922,3288,3653  (CloudWatch's fixed set — anything else fails at synth),
+#            or 'infinite' to never expire.
+LAMBDA_LOG_RETENTION_DAYS=
+# X-Ray tracing is billed per recorded trace. Unset → disabled in dev, active otherwise.
+#   active | disabled | pass_through
+LAMBDA_TRACING=
 LAMBDA_APP_URL=
 LAMBDA_SUPPORT_EMAIL=
 LAMBDA_CORS_ORIGINS=

package/README.md

@@ -28,17 +28,30 @@ process env.
 
 ### Naming convention
 
-Everything is named from `--stage` (`dev|staging|prod`) and `--project` (default
-`default`). With the default project, `app = auth-craft`; otherwise `app = auth-craft-<project>`.
+Pattern: **`{app}-{env}-{layer}-{component}`**.
+
+- **`app`** — `auth-craft` by default; `auth-craft-<project>` with `--project`; or a full
+  rebrand with `--app-name` / `AUTH_CRAFT_APP_NAME` (e.g. `snapshot-commerce`).
+- **`env`** — `--stage` (`dev|staging|prod`).
+- **`layer`** — `--layer` / `LAYER`, default `auth`. Namespaces this deploy within a larger
+  app that has other layers (e.g. `--layer billing`), so the CLI is reused per layer.
+- **`component`** — per-resource: `data` (table), `api` (Lambda), `system`/`tenant`/`customer`
+  (gateway workers).
 
 | Resource | Name |
 |----------|------|
-| CDK stacks | `<app>-<stage>-data`, `<app>-<stage>-api` |
-| Lambda fn + DynamoDB table | `<app>-<stage>` |
-| Gateway workers (`multi`) | `<app>-<stage>-system` / `-tenant` / `-customer` |
-| Gateway worker (`shared`) | `<app>-<stage>` |
-
-So `outputs`/`gateway` look up the api stack `<app>-<stage>-api`. The CDK output keys are
+| CDK stacks | `<app>-<env>-<layer>-data`, `<app>-<env>-<layer>-api` |
+| DynamoDB table | `<app>-<env>-<layer>-data` |
+| Lambda fn (+ log group) | `<app>-<env>-<layer>-api` |
+| Gateway workers (`multi`) | `<app>-<env>-<layer>-system` / `-tenant` / `-customer` |
+| Gateway worker (`shared`) | `<app>-<env>-<layer>` |
+| `AUTH_SYSTEM_NAME` / JWT issuer | `<app>-<env>-<layer>` (no component — keeps the `iss` claim stable) |
+
+Example (`--app-name snapshot-commerce --stage prod`, default layer):
+`snapshot-commerce-prod-auth-data` (table), `snapshot-commerce-prod-auth-api` (Lambda),
+`snapshot-commerce-prod-auth-system` (worker), issuer `snapshot-commerce-prod-auth`.
+
+So `outputs`/`gateway` look up the api stack `<app>-<env>-<layer>-api`. The CDK output keys are
 `LambdaFunctionUrl`, `ApiBasePath`, `AuthSystemName`, `DynamoDBTableName`.
 
 ### Deploy model (multi vs shared)
@@ -150,6 +163,43 @@ CF_EDGE_GATE_SECRET="$SNAP_EDGE" CLOUDFLARE_ACCOUNT_ID="$SNAP_CF_ACCT" \
   npx auth-craft-stack all --stage "$STAGE"
 ```
 
+## Observability cost controls (log retention, tracing)
+
+CloudWatch Logs and X-Ray are usually the two line items that make a low-traffic **dev**
+stage cost more than the Lambda itself. Both are configurable, with stage-aware defaults
+that keep dev cheap without touching staging/prod behaviour:
+
+| Setting | Env var / flag | Default (dev) | Default (staging/prod) |
+|---------|----------------|---------------|------------------------|
+| Log retention | `LAMBDA_LOG_RETENTION_DAYS` / `--log-retention-days` | `3` days | `30` days |
+| X-Ray tracing | `LAMBDA_TRACING` / `--tracing` | `disabled` | `active` |
+
+```bash
+# Cheapest dev: keep 1 day of logs, no tracing (tracing is already off by default in dev)
+npx auth-craft-stack lambda --stage dev --log-retention-days 1
+
+# Turn tracing back on in dev while debugging
+npx auth-craft-stack lambda --stage dev --tracing active
+
+# Long retention for an audited prod
+npx auth-craft-stack lambda --stage prod --log-retention-days 365
+```
+
+Notes:
+- Retention accepts only **CloudWatch's fixed set** — `1, 3, 5, 7, 14, 30, 60, 90, 120, 150,
+  180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653` — or `infinite` to never
+  expire. Any other value fails at **synth** time with the valid list, so a typo can't
+  silently deploy the wrong retention.
+- Retention caps **storage** cost only; you are still billed for log **ingestion**. To cut
+  ingestion, reduce what the app logs.
+- Changing retention applies to the existing log group too (it's the same CloudFormation
+  resource), so old logs beyond the new window age out — it is not just for new logs.
+- In `prod` the log group has `RemovalPolicy.RETAIN`, so destroying the stack keeps the logs
+  (and the group must be deleted manually before a same-name redeploy). In dev/staging it is
+  destroyed with the stack.
+- `LogRetentionDays` and `TracingMode` are emitted as CDK outputs, so
+  `npx auth-craft-stack outputs` shows what is actually deployed.
+
 ## CORS (per scope + dynamic allowlist)
 
 CORS is resolved **per scope** (system / tenant / customer) — the 3 workers no longer
@@ -214,8 +264,8 @@ worker names + a ready-to-paste snippet are in `auth-craft-stack outputs`:
 ```jsonc
 // auth-craft-stack outputs  →
 {
-  "workerNames": { "system": "auth-craft-prod-system", "tenant": "...", "customer": "auth-craft-prod-customer" },
-  "pagesProxy": { "serviceBindingExample": "[[services]]\nbinding = \"AUTH_GATEWAY\"\nservice = \"auth-craft-prod-customer\"\n" }
+  "workerNames": { "system": "auth-craft-prod-auth-system", "tenant": "...", "customer": "auth-craft-prod-auth-customer" },
+  "pagesProxy": { "serviceBindingExample": "[[services]]\nbinding = \"AUTH_GATEWAY\"\nservice = \"auth-craft-prod-auth-customer\"\n" }
 }
 ```
 
@@ -225,7 +275,7 @@ In the Pages app:
 # wrangler.toml (your Pages project)  — bind the gateway worker for the scope this app serves
 [[services]]
 binding = "AUTH_GATEWAY"
-service = "auth-craft-prod-customer"   # from outputs.workerNames.<scope>
+service = "auth-craft-prod-auth-customer"   # from outputs.workerNames.<scope>
 ```
 
 ```ts