@auth-craft/aws-cf-stack 1.7.1 → 1.8.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"

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)
@@ -214,8 +227,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 +238,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

package/bin/deploy.sh

@@ -44,6 +44,9 @@ Options (each also reads an env var; the flag wins):
   --stage <dev|staging|prod>   Stage          (env STAGE, default dev; accepts production/development)
   --project <name>             CDK project     (env PROJECT, default "default")
   --app-name <name>            Override app name (env AUTH_CRAFT_APP_NAME; default auth-craft[-project])
+  --layer <name>               Layer namespace within the app (env LAYER, default "auth").
+                               Resource names are {app}-{env}-{layer}-{component}, so a larger
+                               app with other layers (e.g. billing) reuses this CLI per layer.
   --region <region>            AWS region      (env LAMBDA_AWS_REGION, default us-east-1)
   --gateway-secret <v>         env LAMBDA_GATEWAY_SECRET
   --jwt-public-key <v>         env LAMBDA_JWT_PUBLIC_KEY
@@ -78,6 +81,7 @@ while [[ $# -gt 0 ]]; do
     --stage)            FLAG[STAGE]="${2:?}"; shift 2 ;;
     --project)          FLAG[PROJECT]="${2:?}"; shift 2 ;;
     --app-name)         FLAG[AUTH_CRAFT_APP_NAME]="${2:?}"; shift 2 ;;
+    --layer)            FLAG[LAYER]="${2:?}"; shift 2 ;;
     --region)           FLAG[LAMBDA_AWS_REGION]="${2:?}"; shift 2 ;;
     --gateway-secret)   FLAG[LAMBDA_GATEWAY_SECRET]="${2:?}"; shift 2 ;;
     --jwt-public-key)   FLAG[LAMBDA_JWT_PUBLIC_KEY]="${2:?}"; shift 2 ;;
@@ -142,7 +146,7 @@ case "$COMMAND" in
     # if not already exported in this process (e.g. snapshot drove `lambda` separately).
     if [[ -z "${LAMBDA_FUNCTION_URL:-}" || -z "${API_BASE_PATH:-}" ]]; then
       require_aws_identity
-      api_stack="${APP_NAME}-${STAGE}-api"
+      api_stack="${RESOURCE_NAME}-api"
       LAMBDA_FUNCTION_URL="$(cfn_output "$api_stack" LambdaFunctionUrl)"
       API_BASE_PATH="$(cfn_output "$api_stack" ApiBasePath)"
       AUTH_SYSTEM_NAME="$(cfn_output "$api_stack" AuthSystemName)"

package/cdk/bin/app.ts

@@ -10,6 +10,7 @@ const app = new cdk.App();
 const rawStage = process.env.STAGE || 'dev';
 const stage = rawStage === 'production' ? 'prod' : rawStage === 'development' ? 'dev' : rawStage;
 const project = process.env.PROJECT || 'default'; // Client project name
+const layer = process.env.LAYER || 'auth'; // Layer namespace within the app (default "auth")
 
 const env = {
   account: process.env.CDK_DEFAULT_ACCOUNT,
@@ -17,18 +18,25 @@ const env = {
 };
 
 // ==================== Naming Convention ====================
-// Stack naming: {app}-{env}-{layer}
-//   - app: AUTH_CRAFT_APP_NAME if set, else "auth-craft" (base) / "auth-craft-{project}"
-//   - env: "dev", "staging", "prod"
-//   - layer: "data", "api"
-//   Examples: auth-craft-dev-data, auth-craft-staging-api, snapshot-auth-prod-api
+// Pattern: {app}-{env}-{layer}-{component}
+//   - app:   AUTH_CRAFT_APP_NAME if set, else "auth-craft" (base) / "auth-craft-{project}"
+//   - env:   "dev", "staging", "prod"
+//   - layer: LAYER (default "auth") — namespaces this deploy within a larger app
+//   - component: per-resource suffix ("data" for the table, "api" for the Lambda)
+//   The {app}-{env}-{layer} base is the resourceName (AUTH_SYSTEM_NAME / JWT issuer);
+//   it carries no component so the iss claim stays stable across resources.
+//   Examples: snapshot-commerce-prod-auth-data, snapshot-commerce-prod-auth-api
 
 const appName =
   process.env.AUTH_CRAFT_APP_NAME || (project === 'default' ? 'auth-craft' : `auth-craft-${project}`);
 
+// Base name shared by every resource (also AUTH_SYSTEM_NAME / JWT issuer).
+const resourceBase = `${appName}-${stage}-${layer}`;
+
 console.log(`🚀 Deploying Auth Craft to AWS`);
 console.log(`   App: ${appName}`);
 console.log(`   Stage: ${stage}`);
+console.log(`   Layer: ${layer}`);
 console.log(`   Region: ${env.region}`);
 
 // Common tags for cost allocation
@@ -39,30 +47,29 @@ const costTags = {
   ManagedBy: 'CDK',
 };
 
-// Stack naming helper: {app}-{env}-{layer}
-const getStackName = (layer: string) => `${appName}-${stage}-${layer}`;
-
-// Resource naming helper: {app}-{env}
-const getResourceName = () => `${appName}-${stage}`;
+// Stack / resource naming helper: {app}-{env}-{layer}-{component}
+const nameFor = (component: string) => `${resourceBase}-${component}`;
 
-// DynamoDB Stack (data layer)
-const dynamodbStack = new DynamoDBStack(app, `${appName}-${stage}-data`, {
+// DynamoDB Stack (data component)
+const dynamodbStack = new DynamoDBStack(app, nameFor('data'), {
   env,
-  stackName: getStackName('data'),
-  description: `Auth Craft DynamoDB (${appName}-${stage})`,
+  stackName: nameFor('data'),
+  description: `Auth Craft DynamoDB (${resourceBase})`,
   tags: costTags,
-  resourceName: getResourceName(),
+  tableName: nameFor('data'),
   stage,
 });
 
-// Lambda Stack (api layer)
-const lambdaStack = new LambdaStack(app, `${appName}-${stage}-api`, {
+// Lambda Stack (api component)
+const lambdaStack = new LambdaStack(app, nameFor('api'), {
   env,
-  stackName: getStackName('api'),
-  description: `Auth Craft Lambda API (${appName}-${stage})`,
+  stackName: nameFor('api'),
+  description: `Auth Craft Lambda API (${resourceBase})`,
   table: dynamodbStack.table,
   tags: costTags,
-  resourceName: getResourceName(),
+  functionName: nameFor('api'),
+  // Base {app}-{env}-{layer} — AUTH_SYSTEM_NAME / JWT issuer (no component).
+  resourceName: resourceBase,
   stage,
 });