@auth-craft/aws-cf-stack 1.0.0 → 1.1.0

package/.env.example

@@ -10,9 +10,17 @@
 #
 # Required vs optional is marked per line.
 
-# ─── Stage / project ─────────────────────────────────────────────────────────
+# ─── Stage / project / naming ────────────────────────────────────────────────
 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.
+
+# ─── Tool command overrides (optional — pin your own binaries) ───────────────
+AUTH_CRAFT_WRANGLER_CMD=      # optional — e.g. "pnpm wrangler"; default "npx --yes wrangler"
+AUTH_CRAFT_CDK_CMD=           # optional — e.g. "pnpm cdk";      default "npx cdk"
 
 # ─── AWS ─────────────────────────────────────────────────────────────────────
 LAMBDA_AWS_REGION=us-east-1   # optional (flag --region), default us-east-1
@@ -33,7 +41,9 @@ LAMBDA_JWT_REFRESH_TOKEN_AUDIENCE=refresh  # optional, default refresh
 LAMBDA_GATEWAY_SECRET=        # required for staging/prod (flag --gateway-secret)
 
 # ─── API base path (stable obfuscated path; keep it fixed across deploys) ─────
-LAMBDA_APP_BASE_PATH=         # optional — if unset, a random path is generated each deploy
+LAMBDA_APP_BASE_PATH=         # recommended — set a stable, non-guessable value (e.g. /api-7f3a).
+                              #   Unset = fixed default '/api' (NOT random) + a warning. Never
+                              #   changes between deploys, so clients/workers don't break.
 
 # ─── Cloudflare gateway workers ──────────────────────────────────────────────
 CLOUDFLARE_API_TOKEN=         # required for gateway (flag --cf-api-token)
@@ -59,7 +69,11 @@ LAMBDA_INTERNAL_JWT_ISSUER=auth-craft    # optional
 LAMBDA_SERVICE_ROUTE_PATH=/internal      # optional, default /internal
 
 # ─── Gateway JWT verification on the Lambda (optional) ────────────────────────
-LAMBDA_GATEWAY_JWT_PUBLIC_KEY_HEX=       # optional — 64 hex chars; Lambda verifies worker JWT
+# One key pair: the worker signs with CF_GATEWAY_JWT_PRIVATE_KEY (JWK base64, above),
+# the Lambda verifies with the matching public key as hex below. If you set ONLY the
+# private JWK, the package DERIVES this hex from it automatically (single source, no drift) —
+# so leave this blank unless you intentionally want a different verify key.
+LAMBDA_GATEWAY_JWT_PUBLIC_KEY_HEX=       # optional — 64 hex chars; auto-derived from CF_GATEWAY_JWT_PRIVATE_KEY if unset
 LAMBDA_GATEWAY_JWT_ISSUER=bff-worker     # optional
 LAMBDA_GATEWAY_JWT_AUDIENCE=auth-craft:backend  # optional
 LAMBDA_GATEWAY_JWT_HEADER=x-gateway-auth # optional

package/README.md

@@ -46,7 +46,7 @@ So `outputs`/`gateway` look up the api stack `<app>-<stage>-api`. The CDK output
 | `admin`   | Create the super-admin (idempotent; **skips** if `LAMBDA_SUPER_ADMIN_*` / `LAMBDA_AUTH_SETUP_TOKEN` unset; "already exists" = success). |
 | `gateway` | Deploy the 3 gateway workers. Re-reads the Lambda outputs from CloudFormation if run as a separate invocation. |
 | `all`     | `lambda` → `admin` → `gateway`, one run. |
-| `outputs` | Print the live api-stack outputs as JSON (no deploy), incl. derived `backendUrl`. For self-driving callers. |
+| `outputs` | Print the live api-stack outputs as JSON (no deploy): `backendUrl`, `apiBasePath`, `dynamodbTable`, and the auth keys read **from the live Lambda config** (`jwtPublicKey`, `jwtIssuer`, `jwtAlgorithm`, `serviceJwtPublicKey`) + `gatewayUrls`/`routePrefixes`. Self-contained — works standalone (no env), so an orchestrator can auto-fill its `*_AUTH_*` vars. |
 
 ## Requirements (on the deploying machine)
 
@@ -147,6 +147,19 @@ time). Bump the version to deploy newer auth-craft.
   `gateway` from the **same** value.
 - **`gateway` can't read Lambda outputs** — deploy the `lambda` stage first (it reads the live
   `<app>-<stage>-api` stack).
+- **Queue email silently not sent** — with `LAMBDA_EMAIL_MODE=queue`, the SQS queue must exist
+  **before** the `lambda` stage: pass `LAMBDA_EMAIL_QUEUE_ARN`/`LAMBDA_EMAIL_QUEUE_URL` of an
+  already-deployed queue. The stack grants the Lambda `sqs:SendMessage` on that ARN, but it
+  can't create a cross-stack queue — deploy your email/queue stack first, then this one.
+
+## Email delivery modes
+
+`LAMBDA_EMAIL_MODE` = `console` (default) | `smtp` | `queue`.
+- **queue** (e.g. an existing SQS-backed email service): set `LAMBDA_EMAIL_QUEUE_ARN` +
+  `LAMBDA_EMAIL_QUEUE_URL` (+ region/envelope, see `.env.example`). **Ordering matters** — the
+  queue is a cross-stack resource this package does not create; deploy it first. The `lambda`
+  stage then grants the auth Lambda `sqs:SendMessage` on that ARN automatically.
+- **smtp**: set `LAMBDA_SMTP_*`. **console**: logs only (dev).
 
 ## How it's built (maintainers)
 

package/bin/deploy.sh

@@ -41,8 +41,9 @@ Commands:
              derived backendUrl (FunctionUrl+ApiBasePath) — for self-driving callers.
 
 Options (each also reads an env var; the flag wins):
-  --stage <dev|staging|prod>   Stage          (env STAGE, default dev)
+  --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])
   --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
@@ -76,6 +77,7 @@ while [[ $# -gt 0 ]]; do
     lambda|gateway|admin|all|outputs) COMMAND="$1"; shift ;;
     --stage)            FLAG[STAGE]="${2:?}"; shift 2 ;;
     --project)          FLAG[PROJECT]="${2:?}"; shift 2 ;;
+    --app-name)         FLAG[AUTH_CRAFT_APP_NAME]="${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 ;;
@@ -103,6 +105,9 @@ export AWS_REGION="${LAMBDA_AWS_REGION:-${AWS_REGION:-us-east-1}}"
 export LAMBDA_AWS_REGION="$AWS_REGION"
 
 derive_naming
+# #5 — derive the Lambda's gateway-JWT public hex from the worker's private JWK when
+# only the private key is provided, so the verify/sign pair can never drift.
+derive_gateway_jwt_public_hex
 
 # ── Dispatch ──────────────────────────────────────────────────────────────────
 print_summary() {

package/cdk/bin/app.ts

@@ -5,7 +5,10 @@ import { LambdaStack } from '../lib/lambda-stack';
 
 const app = new cdk.App();
 
-const stage = process.env.STAGE || 'dev';
+// Stage — normalize the common aliases so the stack accepts either form (the shell
+// normalizes too; this keeps the CDK app correct if invoked directly).
+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 env = {
@@ -15,13 +18,13 @@ const env = {
 
 // ==================== Naming Convention ====================
 // Stack naming: {app}-{env}-{layer}
-//   - app: "auth-craft" (base) or "auth-craft-{project}" (multi-project)
+//   - 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, auth-craft-prod-data
-//   Multi-project: auth-craft-ecommerce-dev-data, auth-craft-saas-prod-api
+//   Examples: auth-craft-dev-data, auth-craft-staging-api, snapshot-auth-prod-api
 
-const appName = project === 'default' ? 'auth-craft' : `auth-craft-${project}`;
+const appName =
+  process.env.AUTH_CRAFT_APP_NAME || (project === 'default' ? 'auth-craft' : `auth-craft-${project}`);
 
 console.log(`🚀 Deploying Auth Craft to AWS`);
 console.log(`   App: ${appName}`);
@@ -49,6 +52,7 @@ const dynamodbStack = new DynamoDBStack(app, `${appName}-${stage}-data`, {
   description: `Auth Craft DynamoDB (${appName}-${stage})`,
   tags: costTags,
   resourceName: getResourceName(),
+  stage,
 });
 
 // Lambda Stack (api layer)
@@ -59,6 +63,7 @@ const lambdaStack = new LambdaStack(app, `${appName}-${stage}-api`, {
   table: dynamodbStack.table,
   tags: costTags,
   resourceName: getResourceName(),
+  stage,
 });
 
 // Lambda stack depends on DynamoDB stack

package/cdk/lib/dynamodb-stack.ts

@@ -4,6 +4,7 @@ import type { Construct } from 'constructs';
 
 interface DynamoDBStackProps extends cdk.StackProps {
   resourceName: string; // e.g., "auth-craft-dev", "auth-craft-prod"
+  stage: string; // "dev" | "staging" | "prod" — passed from the app, single source of truth
 }
 
 export class DynamoDBStack extends cdk.Stack {
@@ -12,8 +13,7 @@ export class DynamoDBStack extends cdk.Stack {
   constructor(scope: Construct, id: string, props: DynamoDBStackProps) {
     super(scope, id, props);
 
-    const stage = process.env.STAGE || 'dev';
-    const { resourceName } = props;
+    const { resourceName, stage } = props;
 
     // Resource naming: {app}-{env}
     // Examples: auth-craft-dev, auth-craft-staging, auth-craft-prod

package/cdk/lib/lambda-stack.ts

@@ -1,4 +1,3 @@
-import * as crypto from 'node:crypto';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as cdk from 'aws-cdk-lib';
@@ -20,6 +19,7 @@ const LAMBDA_ASSET_DIR = path.resolve(__dirname, '../../assets/lambda');
 interface LambdaStackProps extends cdk.StackProps {
   table: dynamodb.ITable;
   resourceName: string; // e.g., "auth-craft-dev", "auth-craft-prod"
+  stage: string; // "dev" | "staging" | "prod" — passed from the app, single source of truth
 }
 
 export class LambdaStack extends cdk.Stack {
@@ -30,23 +30,25 @@ export class LambdaStack extends cdk.Stack {
   constructor(scope: Construct, id: string, props: LambdaStackProps) {
     super(scope, id, props);
 
-    const stage = process.env.STAGE || 'dev';
-    const { resourceName } = props;
+    const { resourceName, stage } = props;
 
-    // API base path — obscures the Lambda route surface.
-    // Prefer an explicit, stable value from env (CI/CD: LAMBDA_APP_BASE_PATH) so
-    // it does NOT change between deploys (a random one breaks every client that
-    // has the path configured). Falls back to a one-off random path only when
-    // unset. Normalized to a single leading '/', no trailing '/'.
+    // API base path — obscures the Lambda route surface and is forwarded onto by
+    // the gateway worker (BACKEND_URL = FunctionUrl + this path). It MUST be stable
+    // across deploys — a value that changes breaks every client/worker that has the
+    // path configured. So this package NEVER randomizes it: take the explicit env
+    // value, else a fixed default. Normalized to a single leading '/', no trailing '/'.
+    const DEFAULT_BASE_PATH = '/api';
     const configuredBasePath = process.env.LAMBDA_APP_BASE_PATH?.trim();
-    if (configuredBasePath) {
-      const withLeading = configuredBasePath.startsWith('/') ? configuredBasePath : `/${configuredBasePath}`;
-      this.apiBasePath = withLeading.endsWith('/') ? withLeading.slice(0, -1) : withLeading;
-    } else {
-      // Format: /{16-char-random-hex} e.g., /a1b2c3d4e5f6g7h8
-      const randomPath = crypto.randomBytes(8).toString('hex');
-      this.apiBasePath = `/${randomPath}`;
+    const rawBasePath = configuredBasePath || DEFAULT_BASE_PATH;
+    if (!configuredBasePath) {
+      console.warn(
+        `⚠️  LAMBDA_APP_BASE_PATH not set — using the fixed default '${DEFAULT_BASE_PATH}'. ` +
+          'Set a stable, non-guessable value (e.g. /api-7f3a) to obscure the route surface; ' +
+          'it must stay the same across deploys.',
+      );
     }
+    const withLeading = rawBasePath.startsWith('/') ? rawBasePath : `/${rawBasePath}`;
+    this.apiBasePath = withLeading.endsWith('/') ? withLeading.slice(0, -1) : withLeading;
 
     // Get environment variables
     // CI/CD passes secrets with LAMBDA_ prefix — strip when injecting into Lambda runtime

package/lib/common.sh

@@ -76,24 +76,59 @@ load_env_file() {
 }
 
 # ── Stage / naming derivation (mirrors the CI workflow + CDK app.ts) ──────────
-# Inputs: STAGE, PROJECT. Exports APP_NAME, RESOURCE_NAME, RUNTIME_NODE_ENV.
+# Inputs: STAGE, PROJECT, optional AUTH_CRAFT_APP_NAME.
+# Exports STAGE (normalized), PROJECT, APP_NAME, RESOURCE_NAME, RUNTIME_NODE_ENV.
 derive_naming() {
   STAGE="${STAGE:-dev}"
   PROJECT="${PROJECT:-default}"
+
+  # #2 Normalize common stage aliases so a consumer can pass either form.
+  #   production -> prod, development -> dev, staging stays staging.
+  case "$STAGE" in
+    production) STAGE="prod" ;;
+    development) STAGE="dev" ;;
+  esac
   case "$STAGE" in
     dev|staging|prod) ;;
-    *) die "Invalid --stage: $STAGE (expected dev|staging|prod)" ;;
+    *) die "Invalid --stage: $STAGE (expected dev|staging|prod, or production/development)" ;;
   esac
-  if [[ "$PROJECT" == "default" ]]; then
+
+  # #1 App name: explicit override wins, else derive from PROJECT (default auth-craft).
+  #   Lets a consumer brand it (e.g. snapshot-auth) without changing the default.
+  if [[ -n "${AUTH_CRAFT_APP_NAME:-}" ]]; then
+    APP_NAME="$AUTH_CRAFT_APP_NAME"
+  elif [[ "$PROJECT" == "default" ]]; then
     APP_NAME="auth-craft"
   else
     APP_NAME="auth-craft-${PROJECT}"
   fi
+
   RESOURCE_NAME="${APP_NAME}-${STAGE}"
   RUNTIME_NODE_ENV="$([[ "$STAGE" == "prod" ]] && echo production || echo development)"
   export STAGE PROJECT APP_NAME RESOURCE_NAME RUNTIME_NODE_ENV
 }
 
+# ── Gateway JWT key pair (#5: one source, derive the rest) ────────────────────
+# The worker signs a Gateway JWT with an Ed25519 private key (JWK base64,
+# CF_GATEWAY_JWT_PRIVATE_KEY); the Lambda verifies it with the matching public key
+# as raw hex (LAMBDA_GATEWAY_JWT_PUBLIC_KEY_HEX). These are ONE key pair passed as two
+# vars in two formats — easy to drift. If the private JWK is set but the public hex is
+# not, derive the hex from the JWK so both always come from a single source.
+derive_gateway_jwt_public_hex() {
+  [[ -z "${CF_GATEWAY_JWT_PRIVATE_KEY:-}" ]] && return 0
+  [[ -n "${LAMBDA_GATEWAY_JWT_PUBLIC_KEY_HEX:-}" ]] && return 0
+  require_cmd node
+  local hex
+  hex="$(CF_GATEWAY_JWT_PRIVATE_KEY="$CF_GATEWAY_JWT_PRIVATE_KEY" node -e '
+    const raw = process.env.CF_GATEWAY_JWT_PRIVATE_KEY;
+    const jwk = JSON.parse(Buffer.from(raw, "base64").toString());
+    if (!jwk.x) throw new Error("CF_GATEWAY_JWT_PRIVATE_KEY JWK has no public component (x)");
+    process.stdout.write(Buffer.from(jwk.x, "base64url").toString("hex"));
+  ')" || die "Failed to derive gateway JWT public hex from CF_GATEWAY_JWT_PRIVATE_KEY"
+  export LAMBDA_GATEWAY_JWT_PUBLIC_KEY_HEX="$hex"
+  info "Derived LAMBDA_GATEWAY_JWT_PUBLIC_KEY_HEX from CF_GATEWAY_JWT_PRIVATE_KEY (single source)."
+}
+
 # ── AWS ───────────────────────────────────────────────────────────────────────
 require_aws_identity() {
   require_cmd aws
@@ -107,13 +142,12 @@ require_aws_identity() {
 }
 
 ensure_bootstrap() {
-  require_cmd npx
   local region="${1:-$AWS_REGION}"
   if aws ssm get-parameter --name /cdk-bootstrap/hnb659fds/version --region "$region" >/dev/null 2>&1; then
     info "CDK already bootstrapped in $region"
   else
     info "Bootstrapping CDK in $region…"
-    (cd "$CDK_DIR" && npx cdk bootstrap "aws://${AWS_ACCOUNT_ID}/${region}")
+    (cd "$CDK_DIR" && cdk bootstrap "aws://${AWS_ACCOUNT_ID}/${region}")
   fi
 }
 
@@ -132,33 +166,107 @@ cfn_output() {
     --output text --region "$AWS_REGION" 2>/dev/null || true
 }
 
+# Read one environment variable from a deployed Lambda's live config. Lets `outputs`
+# be self-contained (read what the Lambda actually runs with) instead of depending on
+# the caller's process env. Note the runtime var names differ from the LAMBDA_* inputs
+# (e.g. JWT_PUBLIC_KEY, not LAMBDA_JWT_PUBLIC_KEY).
+lambda_env() {
+  local fn="$1" key="$2"
+  require_cmd aws
+  aws lambda get-function-configuration --function-name "$fn" --region "$AWS_REGION" \
+    --query "Environment.Variables.${key}" --output text 2>/dev/null | sed 's/^None$//' || true
+}
+
+# Derive a gateway worker URL for a scope (custom domain > workers.dev > empty).
+gateway_url_for() {
+  local scope="$1" upper dom_var custom
+  upper="$(echo "$scope" | tr '[:lower:]' '[:upper:]')"
+  dom_var="CF_WORKER_CUSTOM_DOMAIN_${upper}"
+  custom="${!dom_var:-}"
+  if [[ -n "$custom" ]]; then
+    echo "https://$custom"
+  elif [[ -n "${CF_WORKERS_SUBDOMAIN:-}" ]]; then
+    echo "https://${APP_NAME}-${STAGE}-${scope}.${CF_WORKERS_SUBDOMAIN}.workers.dev"
+  else
+    echo ""
+  fi
+}
+
 # Print the live deploy outputs of the existing api stack as JSON, for an
-# orchestrator that drives its own steps between stages. Keys mirror what the
-# stages produce: lambdaFunctionUrl, apiBasePath, authSystemName, dynamodbTable,
-# and the derived backendUrl (= functionUrl + basePath, the anti-drift value).
+# orchestrator that drives its own steps between stages and wants to AUTO-FILL its
+# own *_AUTH_* vars without copying anything by hand. SELF-CONTAINED: the JWT keys /
+# issuer / alg are read from the LIVE Lambda config (get-function-configuration), so it
+# works when run standalone (no env), falling back to process env only if the read is
+# empty. Includes:
+#   - lambdaFunctionUrl, apiBasePath, authSystemName, dynamodbTable
+#   - backendUrl (= functionUrl + basePath, the anti-drift value)
+#   - jwtPublicKey + jwtIssuer + jwtAlgorithm + serviceJwtPublicKey (from the Lambda)
+#   - gatewayUrls{system,tenant,customer} + routePrefixes{...}
 print_outputs_json() {
   require_cmd aws; require_cmd jq
   require_aws_identity
   local api_stack="${APP_NAME}-${STAGE}-api"
-  local url base name table backend
+  local url base name table fn backend issuer
   url="$(cfn_output "$api_stack" LambdaFunctionUrl)"
   base="$(cfn_output "$api_stack" ApiBasePath)"
   name="$(cfn_output "$api_stack" AuthSystemName)"
   table="$(cfn_output "$api_stack" DynamoDBTableName)"
+  fn="$(cfn_output "$api_stack" LambdaFunctionName)"
   [[ -n "$url" && "$url" != "None" ]] \
     || die "No outputs for stack $api_stack in $AWS_REGION — deploy the lambda stage first."
   backend="${url%/}${base}"
+
+  # Read the auth-relevant values from the LIVE Lambda config so `outputs` is
+  # self-contained (works when run standalone, e.g. deploying the BFF later in a
+  # separate process). Fall back to the caller's process env if the Lambda read is
+  # empty. Runtime var names differ from the LAMBDA_* inputs.
+  local jwtPub jwtIssuer jwtAlg svcPub
+  [[ -n "$fn" && "$fn" != "None" ]] || fn="$name"
+  jwtPub="$(lambda_env "$fn" JWT_PUBLIC_KEY)";            jwtPub="${jwtPub:-${LAMBDA_JWT_PUBLIC_KEY:-}}"
+  jwtIssuer="$(lambda_env "$fn" JWT_ISSUER)";             jwtIssuer="${jwtIssuer:-${LAMBDA_JWT_ISSUER:-$name}}"
+  jwtAlg="$(lambda_env "$fn" JWT_ALGORITHM)";             jwtAlg="${jwtAlg:-${LAMBDA_JWT_ALGORITHM:-EdDSA}}"
+  svcPub="$(lambda_env "$fn" INTERNAL_JWT_PUBLIC_KEY)";   svcPub="${svcPub:-${LAMBDA_INTERNAL_JWT_PUBLIC_KEY:-}}"
+
   jq -n \
     --arg url "$url" --arg base "$base" --arg name "$name" \
     --arg table "$table" --arg backend "$backend" \
-    --arg stage "$STAGE" --arg project "$PROJECT" --arg region "$AWS_REGION" \
+    --arg stage "$STAGE" --arg project "${PROJECT:-default}" --arg region "$AWS_REGION" \
+    --arg jwtPub "$jwtPub" --arg jwtIssuer "$jwtIssuer" \
+    --arg jwtAlg "$jwtAlg" \
+    --arg svcPub "$svcPub" \
+    --arg gwSystem "$(gateway_url_for system)" \
+    --arg gwTenant "$(gateway_url_for tenant)" \
+    --arg gwCustomer "$(gateway_url_for customer)" \
+    --arg rpSystem "${CF_WORKER_ROUTE_PREFIX_SYSTEM:-/system}" \
+    --arg rpTenant "${CF_WORKER_ROUTE_PREFIX_TENANT:-/tenant}" \
+    --arg rpCustomer "${CF_WORKER_ROUTE_PREFIX_CUSTOMER:-/customer}" \
     '{stage:$stage, project:$project, region:$region,
       lambdaFunctionUrl:$url, apiBasePath:$base, authSystemName:$name,
-      dynamodbTable:$table, backendUrl:$backend}'
+      dynamodbTable:$table, backendUrl:$backend,
+      jwtPublicKey:$jwtPub, jwtIssuer:$jwtIssuer, jwtAlgorithm:$jwtAlg,
+      serviceJwtPublicKey:$svcPub,
+      gatewayUrls:{system:$gwSystem, tenant:$gwTenant, customer:$gwCustomer},
+      routePrefixes:{system:$rpSystem, tenant:$rpTenant, customer:$rpCustomer}}'
 }
 
-# ── wrangler wrapper (quiet, non-interactive) ─────────────────────────────────
+# ── Tool command resolution (#7: let a consumer pin its own binaries) ─────────
+# AUTH_CRAFT_WRANGLER_CMD / AUTH_CRAFT_CDK_CMD override how we invoke the tools.
+# Default to `npx --yes <tool>`. A consumer with a pinned binary (e.g. `pnpm wrangler`
+# or an absolute path) sets these to avoid version drift vs `npx --yes` pulling latest.
 wrangler() {
-  require_cmd npx
-  CI=true WRANGLER_SEND_METRICS=false npx --yes wrangler "$@"
+  if [[ -n "${AUTH_CRAFT_WRANGLER_CMD:-}" ]]; then
+    CI=true WRANGLER_SEND_METRICS=false ${AUTH_CRAFT_WRANGLER_CMD} "$@"
+  else
+    require_cmd npx
+    CI=true WRANGLER_SEND_METRICS=false npx --yes wrangler "$@"
+  fi
+}
+
+cdk() {
+  if [[ -n "${AUTH_CRAFT_CDK_CMD:-}" ]]; then
+    ${AUTH_CRAFT_CDK_CMD} "$@"
+  else
+    require_cmd npx
+    npx cdk "$@"
+  fi
 }

package/lib/deploy-lambda.sh

@@ -8,6 +8,12 @@
 deploy_lambda() {
   header "Deploy Lambda (stage=$STAGE project=$PROJECT region=$AWS_REGION)"
 
+  # #5 — ensure the gateway-JWT public hex is derived BEFORE cdk reads process.env
+  # (the bundled lambda-stack reads LAMBDA_GATEWAY_JWT_PUBLIC_KEY_HEX). Idempotent:
+  # no-op if already set or no private JWK given. Belt-and-suspenders so the pair is
+  # wired even if deploy_lambda is invoked directly (not via the bin entrypoint).
+  derive_gateway_jwt_public_hex
+
   require_aws_identity
   ensure_bootstrap "$AWS_REGION"
 
@@ -24,7 +30,7 @@ deploy_lambda() {
     cd "$CDK_DIR"
     CDK_DEFAULT_ACCOUNT="$AWS_ACCOUNT_ID" \
     CDK_DEFAULT_REGION="$AWS_REGION" \
-      npx cdk deploy --all --require-approval never --outputs-file "$OUTPUTS_FILE"
+      cdk deploy --all --require-approval never --outputs-file "$OUTPUTS_FILE"
   )
 
   [[ -f "$OUTPUTS_FILE" ]] || die "CDK outputs file not written: $OUTPUTS_FILE"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-craft/aws-cf-stack",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Self-contained, versioned distribution of the Auth Craft AWS (DynamoDB + Lambda) + Cloudflare gateway stack. Bundles prebuilt Lambda/worker artifacts + CDK app so consumers deploy without cloning auth-craft.",
   "type": "module",
   "bin": {