hecks 3.5.0 → 3.6.0

data/lib/hecks/projections/deploy/templates/lambda/rust_oauth_policy.tmpl

@@ -0,0 +1,16 @@
+- Statement:
+    - Effect: Allow
+      Action: secretsmanager:GetSecretValue
+      # NAME-BASED, not `!Ref`/`!GetAtt` -- this secret is
+      # never a stack resource (RUSTOAUTH's own Environment
+      # comment, above, has the full story), so there is no
+      # exact ARN to point at. The trailing `-*` is AWS's
+      # own documented pattern for granting a secret known
+      # only by name: every real ARN Secrets Manager mints
+      # is this name plus a random 6-character suffix,
+      # which can't be predicted at template-render time.
+      Resource: !Sub "arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:@@stack_name@@-web-google-oauth-*"
+- Statement:
+    - Effect: Allow
+      Action: secretsmanager:GetSecretValue
+      Resource: !Sub "${@@logical_id@@SessionSecret}"

data/lib/hecks/projections/deploy/templates/lambda/rust_session_secret.tmpl

@@ -0,0 +1,13 @@
+# Auto-generated, never typed or seen -- rust/host's own
+# auth.rs signs both the session cookie and the OAuth `state`
+# token with this. Same ManageMasterUserPassword-style pattern
+# @@db_id@@ already uses for its own password.
+@@logical_id@@SessionSecret:
+  Type: AWS::SecretsManager::Secret
+  Properties:
+    GenerateSecretString:
+      SecretStringTemplate: '{}'
+      GenerateStringKey: session_secret
+      PasswordLength: 64
+      ExcludePunctuation: true
+

data/lib/hecks/projections/deploy/templates/lambda/samconfig.toml.tmpl

@@ -0,0 +1,12 @@
+# GENERATED by hecks deploy project @@domain@@ — re-run it to refresh
+# this file rather than hand-editing.
+version = 0.1
+
+[default.deploy.parameters]
+stack_name = "@@stack_name@@"
+region = "@@region@@"
+resolve_s3 = true
+s3_prefix = "@@stack_name@@"
+capabilities = "CAPABILITY_IAM"
+confirm_changeset = false
+disable_rollback = false

data/lib/hecks/projections/deploy/templates/lambda/shared_note.tmpl

@@ -0,0 +1,6 @@
+# deploy's own last step below looks up @@owner_domain_name@@'s live
+# stack Outputs (never tracked anywhere generated -- same reasoning
+# as WebRedirectBaseUrl's own live lookup above, and the SAME
+# `aws cloudformation describe-stacks` pattern mint-era's own eval
+# chain, below, already proves works against a sibling stack) and
+# passes them as this template's own Owning* Parameters.

data/lib/hecks/projections/deploy/templates/lambda/sync_oauth.tmpl

@@ -0,0 +1,23 @@
+# Owns @@stack_name@@-web-google-oauth's WHOLE lifecycle (create on
+# first run, update every run after — idempotent, cheap, no reason
+# to cache the way patch-pg-native's own multi-minute build does) —
+# deliberately OUTSIDE CloudFormation, straight from @@domain@@'s own
+# gitignored .env.local, so the real client_id/secret never lands in
+# this generated, git-TRACKED template.yaml as plaintext. Read by
+# name (`{{resolve:secretsmanager:@@stack_name@@-web-google-oauth:...}}`,
+# template.yaml's own Environment — @@oauth_function_id@@'s
+# own), not by `!Ref` — see that comment for why this secret isn't a
+# stack resource at all. NOT nested inside patch-pg-native's own
+# pg_version gate above -- a real, live "No rule to make target
+# `sync-google-oauth'" caught that this target used to only exist
+# when a Ruby WebFunction (with its own pg gem) was also present,
+# even though Google OAuth itself has nothing to do with pg at all.
+.PHONY: sync-google-oauth
+sync-google-oauth:
+	@CLIENT_ID=$$(grep '^GOOGLE_CLIENT_ID=' @@domain@@/.env.local | cut -d= -f2-); \
+		CLIENT_SECRET=$$(grep '^GOOGLE_CLIENT_SECRET=' @@domain@@/.env.local | cut -d= -f2-); \
+		test -n "$$CLIENT_ID" -a -n "$$CLIENT_SECRET" || { echo "sync-google-oauth: @@domain@@/.env.local is missing GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET"; exit 1; }; \
+		SECRET_JSON=$$(ruby -rjson -e 'puts JSON.generate({client_id: ARGV[0], client_secret: ARGV[1]})' "$$CLIENT_ID" "$$CLIENT_SECRET"); \
+		aws secretsmanager put-secret-value --secret-id @@stack_name@@-web-google-oauth --secret-string "$$SECRET_JSON" >/dev/null 2>&1 || \
+		aws secretsmanager create-secret --name @@stack_name@@-web-google-oauth --secret-string "$$SECRET_JSON" >/dev/null
+

data/lib/hecks/projections/deploy/templates/lambda/template.yaml.tmpl

@@ -0,0 +1,187 @@
+# GENERATED by hecks deploy project @@domain@@ — re-run it to refresh
+# this file rather than hand-editing. Source: @@world_file@@'s own
+# deployed_to("AwsLambda") block.
+#
+# SELF-CONTAINED, ON PURPOSE — this stack owns its own private VPC,
+# subnets, security groups, and RDS Postgres instance, not just the
+# Lambda. No externally-supplied VPC/database parameters, no
+# DatabaseUrl secret anyone has to type: RDS's own
+# ManageMasterUserPassword generates and stores the password in
+# Secrets Manager, and DATABASE_URL is composed from it via a
+# CloudFormation dynamic reference — resolved at deploy time, never
+# visible in this template, a parameter, or any tool's output.
+#
+# NO NAT GATEWAY for @@logical_id@@ — deliberately. Its own subnets
+# have no route to the internet at all, only to the RDS instance
+# inside the same VPC: dispatch a command, read/write the journal.
+# CloudWatch Logs delivery doesn't go through the function's own VPC
+# networking, so it needs no route either.
+@@nat_comment@@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: >
+  @@infra_name@@ — dispatched through hecks's rust/host, a
+  wasmtime-sandboxed Rust binary with a rehydrate-and-replay Postgres
+  journal (docs/decisions/0018), backed by its own private RDS
+  Postgres instance. PackageType Zip, no container.
+@@parameters_section@@
+Resources:
+  @@network_resources@@
+
+  @@rust_session_secret@@
+  @@logical_id@@:
+    Type: AWS::Serverless::Function@@aurora_depends@@
+    Metadata:
+      BuildMethod: makefile
+    Properties:
+      # PINNED, not SAM's own auto-suffixed default — a Ruby-side
+      # LambdaClient needs to know this function's name AHEAD OF a
+      # first deploy (there's no chicken-egg lookup step), the same
+      # "configured for me, in the projection" standard every other
+      # piece of generated deploy config already holds to. Matches
+      # `stack_name` above exactly — one name, two places it's read
+      # from, never out of sync since both derive from `infra_name`.
+      FunctionName: @@stack_name@@
+      # EXPLICIT, not omitted -- `sam build WebFunction` and
+      # `sam build --use-container WebFunction` run as TWO SEPARATE
+      # single-resource invocations (deploy:'s own comment on why:
+      # cargo-lambda cross-compiles on this host directly, pg's
+      # native extension needs the container -- `--use-container` is
+      # a global sam build flag, can't be scoped per-resource). Each
+      # invocation regenerates .aws-sam/build/template.yaml from
+      # THIS source template for every resource, not just the one it
+      # builds -- a resource with no CodeUri here reverts to
+      # CodeUri-less after the SECOND invocation, and `sam deploy`
+      # then defaults a missing CodeUri to the template's own
+      # containing directory (deploy/@@infra_name@@/ itself),
+      # zipping the whole project tree -- including WebFunction's
+      # own source -- as this function's code. A real, live deploy
+      # shipped exactly that broken artifact (confirmed via
+      # `aws lambda get-function` + downloading the actual deployed
+      # zip). Pinning CodeUri here survives that regeneration: it
+      # still resolves to `.aws-sam/build/@@logical_id@@/`, where
+      # build-@@logical_id@@'s own `cp ... $(ARTIFACTS_DIR)` already
+      # placed the real bootstrap+wasm, regardless of which of the
+      # two sam build calls ran most recently.
+      # "." NOT "@@logical_id@@" -- SAM's Makefile build workflow
+      # requires the Makefile to live INSIDE CodeUri itself
+      # (confirmed live: "Makefile not found at
+      # .../WebFunction/Makefile" when CodeUri named a
+      # directory of its own). This project's one Makefile lives at
+      # the deploy directory's own root, alongside this template --
+      # "." is where it actually is.
+      CodeUri: .
+      PackageType: Zip
+      Runtime: provided.al2023
+      Architectures: [arm64]
+      Handler: bootstrap
+      MemorySize: @@memory@@
+      Timeout: @@timeout@@
+      Environment:
+        Variables:
+          # NOT a `{{resolve:secretsmanager:...}}`-composed DATABASE_URL
+          # anymore (the WebFunction handler below still uses that
+          # mechanism, unchanged) -- that dynamic reference genuinely
+          # IS resolved fresh at deploy time and never rendered into
+          # this template, this tool's output, or the CloudFormation
+          # console. But once it resolves INTO a Lambda's own
+          # Environment.Variables entry, the resolved PLAINTEXT is
+          # stored in the function's OWN configuration:
+          # `lambda:GetFunctionConfiguration` returns it decrypted,
+          # and the Lambda console's Configuration tab displays it, to
+          # ANY principal holding read-only account access (AWS's own
+          # managed ReadOnlyAccess policy included) -- caught
+          # reviewing this template, not live; AWS's own guidance is
+          # to fetch a secret from Secrets Manager at RUNTIME instead,
+          # precisely to avoid this. DB_HOST/DB_NAME/DB_SECRET_ARN
+          # below are not secrets themselves -- an endpoint address, a
+          # database name, and a Secrets Manager ARN authenticate
+          # nothing on their own -- so sitting here as plain
+          # Environment.Variables values costs nothing; main.rs itself
+          # fetches the actual password from Secrets Manager at cold
+          # start, over the AWS SDK, and never hands it back to
+          # CloudFormation or Lambda's own configuration at all.
+          # @@logical_id@@'s own least-privilege Policies grant (below,
+          # sibling of VpcConfig) is the one runtime IAM permission
+          # that fetch needs, scoped to this one secret ARN.
+          @@db_env@@
+          # `domain_name`, NOT `infra_name` — this names the actual
+          # .wasm FILE `hecks build_wasm` writes (rust/dist/@@domain_name@@.wasm,
+          # its own target_mod_name convention, a Rust-build-pipeline
+          # concern unrelated to AWS resource identity) and what the
+          # Makefile below actually bundles into the Lambda package
+          # under. Confirmed the hard way: pinning this to infra_name
+          # alongside the real AWS-identity fields left it looking for
+          # a file `hecks build_wasm` never produces.
+          HECKS_WASM_PATH: !Sub "/var/task/@@domain_name@@.wasm"
+          # STATIC, not a deploy-time parameter — HECKS_DOMAIN is this
+          # domain's own declared name, known at generation time the
+          # same way DBName/HECKS_WASM_PATH already are. HECKS_ERA is
+          # "1" because that's what a FRESH database always gets:
+          # PostgresEra::LineageManager::EraResolver#check! mints era 1
+          # unconditionally the first time any Ruby process boots
+          # against an empty `hecks_eras` (era_resolver.rb's own
+          # `held.empty?` branch) — deterministic, not guessed. `make
+          # mint-era` (this directory's own Makefile) is what actually
+          # triggers that first boot; a LATER real schema evolution
+          # (era 2+) is a separate, later re-generation, not this one.
+          HECKS_DOMAIN: @@declared_domain_name@@
+          # UNCONDITIONAL, not gated on `rust_web` — `rust/host/src/main.rs`'s
+          # own boot sequence reads `ir::ir().ok_or(...)?` for every domain
+          # regardless of web mode (era-lineage bookkeeping needs the IR, not
+          # just the optional in-process web UI), so a Shared-mode domain with
+          # no web layer still needs this sidecar path to boot at all. Previously
+          # gated on `rust_web`, which left every such domain's Lambda crashing
+          # on cold start — checkout.rs's own header flagged this exact
+          # contradiction, confirmed live against Banking's committed template.
+          HECKS_IR_PATH: !Sub "/var/task/@@domain_name@@.ir.json"
+          HECKS_ERA: "1"@@schema_env@@@@rust_oauth_env@@
+      # LEAST-PRIVILEGE -- @@logical_id@@'s own execution role is
+      # otherwise SAM's bare default (logging only); this is the one
+      # runtime AWS permission the DB_SECRET_ARN handling above needs,
+      # scoped to the single secret ARN this stack itself depends on,
+      # never `Resource: "*"`.
+      Policies:
+        - Statement:
+            - Effect: Allow
+              Action: secretsmanager:GetSecretValue
+              Resource: !Sub "${@@db_secret_ref@@}"
+        @@rust_oauth_policy@@
+        # TMPL:cross_domain_lambda_policies
+      VpcConfig:
+        @@vpc_config@@
+      # AWS_IAM by default — this dispatches real domain commands
+      # (cap-table/governance-shaped data);
+      # an unauthenticated public URL is the wrong default for that,
+      # even though it's the simpler one to demo with. NONE only when
+      # `web "Rust"` (rust/host/src/web.rs) makes this the public web
+      # UI itself — safe even though the SAME Function URL also
+      # carries the internal {"verb"}/{"read"} dispatch shapes,
+      # because a Function-URL HTTP event can never be crafted into
+      # that raw top-level shape (Function URLs always wrap the real
+      # HTTP body inside requestContext.http/rawPath/event.body,
+      # unconditionally); that raw shape is reachable only through
+      # the AWS SDK's own IAM-authenticated Invoke API, which never
+      # goes through a Function URL at all.
+      FunctionUrlConfig:
+        AuthType: @@function_url_auth@@
+@@web_function@@
+
+Outputs:
+  FunctionUrl:
+    Value: !GetAtt @@logical_id@@Url.FunctionUrl@@web_function_url_output@@
+  # stack_outputs (hecks deploy project, above the heredocs) is the ONE
+  # place these four names live — DatabaseEndpoint/DatabaseSecretArn
+  # feed `make mint-era`'s own boot step directly; VpcId/
+  # DbSecurityGroupId ALSO feed bastion.yaml's own Parameters (a
+  # separate, sibling stack, created only for the few minutes a mint
+  # takes and destroyed right after, attaching into the SAME private
+  # network without this main template ever knowing a bastion
+  # exists) and the Makefile's own --parameter-overrides. Rename a
+  # key in that table and every consumer follows; reference one that
+  # doesn't exist there and hecks deploy project refuses before
+  # writing a single file, instead of a bastion.yaml whose Parameter
+  # nothing could ever fill. (`PrivateSubnetId` used to sit here too
+  # — dropped, nothing ever consumed it; bastion.yaml mints its own
+  # subnet instead.)
+  @@output_lines@@

data/lib/hecks/projections/deploy/templates/lambda/translation_own.tmpl

@@ -0,0 +1,46 @@
+@@db_env_guard@@
+	@echo "Looking up $(STACK)'s VPC/security group..."
+	@@eval_lines@@
+	@echo "Deploying the temporary bastion stack $(BASTION_STACK)..."
+	aws cloudformation deploy --template-file bastion.yaml --stack-name $(BASTION_STACK) \
+		--parameter-overrides @@parameter_overrides@@ \
+		--capabilities CAPABILITY_IAM
+# DB_PASS_URLENC -- same percent-encoding fix as mint_era_recipe's
+# own comment above the equivalent line in that recipe (libpq's URI
+# parser rejects a bare `%`, which a generated RDS password isn't
+# guaranteed to be free of); this recipe's DATABASE_URL below uses
+# the encoded form for the same reason, even though the script it
+# feeds doesn't currently read it (see db_env_blind above).
+	@INSTANCE_ID=$$(aws cloudformation describe-stacks --stack-name $(BASTION_STACK) --query "Stacks[0].Outputs[?OutputKey=='InstanceId'].OutputValue" --output text); \
+	echo "Waiting for $$INSTANCE_ID to register with SSM..."; \
+	for i in $$(seq 1 30); do \
+		STATUS=$$(aws ssm describe-instance-information --filters "Key=InstanceIds,Values=$$INSTANCE_ID" --query "InstanceInformationList[0].PingStatus" --output text 2>/dev/null); \
+		if [ "$$STATUS" = "Online" ]; then break; fi; \
+		sleep 5; \
+	done; \
+	DB_PASS=$$(aws secretsmanager get-secret-value --secret-id $(DB_SECRET_ARN) --query SecretString --output text | ruby -rjson -e 'print JSON.parse(STDIN.read)["password"]'); \
+	DB_PASS_URLENC=$$(ruby -rerb -e 'print ERB::Util.url_encode(ARGV[0])' "$$DB_PASS"); \
+	RUN_STATUS=1; \
+	for attempt in 1 2 3 4 5; do \
+		kill $$TUNNEL_PID 2>/dev/null; \
+		echo "Opening an SSM tunnel to $(DB_HOST):5432 and running @@verb@@ (attempt $$attempt/5)..."; \
+		aws ssm start-session --target $$INSTANCE_ID \
+			--document-name AWS-StartPortForwardingSessionToRemoteHost \
+			--parameters "{\"host\":[\"$(DB_HOST)\"],\"portNumber\":[\"5432\"],\"localPortNumber\":[\"15432\"]}" \
+			>/tmp/$(BASTION_STACK)-tunnel-$$attempt.log 2>&1 & \
+		TUNNEL_PID=$$!; \
+		for i in $$(seq 1 15); do \
+			nc -z localhost 15432 2>/dev/null && break; \
+			sleep 1; \
+		done; \
+		cd @@cwd@@ && DATABASE_URL="postgres://postgres:$$DB_PASS_URLENC@localhost:15432/@@db_name@@" HECKS_SCHEMA="@@hecks_schema@@" @@run_prefix@@ @@script@@ @@domain_arg_part@@@@extra_args@@&& { RUN_STATUS=0; break; }; \
+		RUN_STATUS=$$?; \
+		echo "@@verb@@ attempt $$attempt/5 failed (exit $$RUN_STATUS) -- restarting the tunnel and retrying in 3s..."; \
+		sleep 3; \
+	done; \
+	kill $$TUNNEL_PID 2>/dev/null; \
+	echo "Tearing down the temporary bastion stack..."; \
+	aws cloudformation delete-stack --stack-name $(BASTION_STACK); \
+	aws cloudformation wait stack-delete-complete --stack-name $(BASTION_STACK); \
+	echo "$(BASTION_STACK) deleted."; \
+	exit $$RUN_STATUS

data/lib/hecks/projections/deploy/templates/lambda/translation_shared.tmpl

@@ -0,0 +1,2 @@
+	@echo "@@verb@@ isn't automated yet for a Shared-mode domain (database \"Shared\") -- see mint-era's own comment in the generated Makefile for the manual path through @@owner_domain_name@@'s own tunnel."; \
+	exit 1

data/lib/hecks/projections/deploy/templates/lambda/web_function.tmpl

@@ -0,0 +1,207 @@
+# THE WEB APP'S OWN LAMBDA — opt-in, see `web_handler_present` above.
+# VPC-attached for the SAME reason @@logical_id@@ is (Member's own
+# persistence needs the private RDS instance directly, permanently —
+# the hecksagon's own comment on why), sharing
+# @@logical_id@@SecurityGroup rather than minting a second one, since
+# both need the identical egress-to-DB rule. That VPC attachment
+# ALSO cuts off the public internet by default (this stack's own "NO
+# NAT GATEWAY" design) — but this function has to reach
+# @@logical_id@@ itself via `lambda:InvokeFunction`, a public AWS API
+# call. @@web_logical_id@@LambdaEndpoint below is the targeted fix: a
+# VPC Interface Endpoint for the Lambda service ONLY (not a NAT
+# Gateway) — a few dollars a month, not a general internet route.
+@@db_id@@LambdaEndpointSecurityGroup:
+  Type: AWS::EC2::SecurityGroup
+  Properties:
+    VpcId: !Ref @@db_id@@Vpc
+    # EC2's own GroupDescription character set excludes apostrophes
+    # too, not just em-dashes -- "this stack's own" was a real,
+    # live rejection ("Invalid security group description").
+    GroupDescription: @@db_id@@LambdaEndpoint - HTTPS from this stacks own Lambdas only
+
+@@db_id@@LambdaEndpointIngress:
+  Type: AWS::EC2::SecurityGroupIngress
+  Properties:
+    GroupId: !Ref @@db_id@@LambdaEndpointSecurityGroup
+    IpProtocol: tcp
+    FromPort: 443
+    ToPort: 443
+    SourceSecurityGroupId: !Ref @@logical_id@@SecurityGroup
+
+@@db_id@@LambdaEndpoint:
+  Type: AWS::EC2::VPCEndpoint
+  Properties:
+    VpcId: !Ref @@db_id@@Vpc
+    ServiceName: !Sub "com.amazonaws.${AWS::Region}.lambda"
+    VpcEndpointType: Interface
+    PrivateDnsEnabled: true
+    SubnetIds: [!Ref @@db_id@@SubnetA, !Ref @@db_id@@SubnetB]
+    SecurityGroupIds: [!Ref @@db_id@@LambdaEndpointSecurityGroup]
+
+# Auto-generated, never typed or seen — the SAME
+# ManageMasterUserPassword pattern @@db_id@@ already uses for its own
+# password, applied to Sinatra's own session-signing secret instead.
+@@web_logical_id@@SessionSecret:
+  Type: AWS::SecretsManager::Secret
+  Properties:
+    GenerateSecretString:
+      SecretStringTemplate: '{}'
+      GenerateStringKey: session_secret
+      PasswordLength: 64
+      ExcludePunctuation: true
+
+@@webhook_secret_resource@@
+@@web_logical_id@@:
+  Type: AWS::Serverless::Function
+  # NO Metadata.BuildMethod — "bundler" isn't a real SAM value (a
+  # real, live UnsupportedBuilderException caught this); `Runtime:
+  # ruby3.2` alone is enough for SAM to select its own built-in Ruby
+  # bundler workflow automatically. @@logical_id@@'s own `BuildMethod:
+  # makefile` above is different: rust/host isn't a runtime SAM
+  # knows how to build at all, so it needs an explicit custom
+  # workflow — this function doesn't. STAYS `ruby3.2` deliberately,
+  # even though `sam validate --lint` now flags it deprecated
+  # (2026-03-31, creation disabled 2027-02-01, still comfortably
+  # ahead of today) — `patch-pg-native`'s own build-ruby3.2 container
+  # image and `lib/3.2/pg_ext.so` path glob (this Makefile, below)
+  # are BOTH hardcoded to this exact runtime; bumping Runtime alone
+  # without reworking that whole from-source pg build for a newer
+  # image is a real, separate undertaking (untested container image
+  # availability, a different vendor/bundle native-extension path)
+  # out of scope here. Matches the live, currently-
+  # deployed choice exactly, so both consumers of this one shared
+  # WebFunction code path stay on the same, PROVEN runtime.
+  Properties:
+    FunctionName: @@stack_name@@-web
+    Runtime: ruby3.2
+    Architectures: [arm64]
+    # THREE parts (file.Class.method), not two — aws-lambda-ric's own
+    # 2-part form calls a plain TOP-LEVEL function via __send__, not
+    # a module method; @@web_handler_relpath@@.rb's own comment on
+    # why its module is named the way it is explains the rest — a
+    # real, live "LambdaHandler is not a module" caught both halves
+    # of this the hard way. `web_handler_relpath` (not a bare
+    # "lambda_handler") whenever `dispatch "None"` moved CodeUri off
+    # @@domain@@ itself — see that variable's own comment, above.
+    Handler: @@web_handler_relpath@@.@@webhook_handler_module@@.lambda_handler
+    CodeUri: @@web_code_uri@@
+    MemorySize: 512
+    Timeout: 15
+    Environment:
+      Variables:
+        DOMAIN_ROOT: /var/task
+        # NOT `declared_domain_name` — `Adapters::Lambda`/
+        # `RemoteDispatcher` both read this to compute WHICH
+        # deployed Lambda function to invoke (`hecks-#{...}`,
+        # matching this stack's own name), a question `infra_name`
+        # answers and a domain's own business identity does not.
+        # Real, live, and confirmed the hard way: this was still
+        # wired to `declared_domain_name` when a client app
+        # first deployed, and WebFunction immediately threw
+        # `ResourceNotFoundException: Function not found:
+        # hecks-<domain>` on every read AND on the
+        # Google OAuth callback itself — a real signed-in user hit
+        # this within minutes of the deploy that introduced it.
+        DOMAIN_NAME: @@infra_name@@
+        HECKS_LAMBDA_ROUTING: "true"
+        HECKS_LAMBDA_REGION: @@region@@@@web_schema_env@@
+        # SAME setting @@domain@@'s own fly.toml/Dockerfile already
+        # sets for the Fly deployment this one replaces — Sinatra's
+        # own `host_authorization` default is only PERMISSIVE in
+        # production mode (an empty `permitted_hosts` list means
+        # "allow any host" — checked directly in rack-protection's
+        # own source); its DEVELOPMENT default is the restrictive
+        # one (only localhost/.test), which is what Sinatra falls
+        # back to when NEITHER RACK_ENV nor APP_ENV is set. A real,
+        # live "Host not permitted" 403 against this function's own
+        # unpredictable *.lambda-url.*.on.aws hostname caught the
+        # gap — this function's Environment never set either var.
+        RACK_ENV: production
+        # The precompiled `pg` gem's aarch64-linux native extension
+        # needs GLIBC 2.29+; Lambda's ruby3.2 MANAGED runtime is
+        # Amazon Linux 2 (glibc 2.26) -- a real, live "Init<NameError>:
+        # uninitialized constant PG::Error" caught this (rescuing
+        # PG::Error itself failed to resolve, because pg's own
+        # require died before reaching the file that defines it).
+        # `make deploy`'s own `patch-pg-native` step (this directory's
+        # Makefile) replaces the broken precompiled extension with one
+        # compiled from source, in-container, against a real
+        # SSL-enabled libpq -- and drops that libpq's .so beside it at
+        # /var/task/lib, found by the dynamic loader with NO explicit
+        # LD_LIBRARY_PATH override needed: the base ruby3.2 image's
+        # own baked-in default (`docker inspect
+        # public.ecr.aws/lambda/ruby:3.2-arm64`) is already
+        # "/var/lang/lib:/lib64:/usr/lib64:/var/runtime:/var/runtime/lib:/var/task:/var/task/lib:/opt/lib"
+        # -- setting LD_LIBRARY_PATH here as a Lambda env var
+        # REPLACES that whole list rather than extending it (a real,
+        # live gotcha: Lambda env vars always fully override a
+        # same-named baked-in image env, never merge with it), which
+        # is exactly what broke Ruby's OWN interpreter startup
+        # ("libcrypt.so.1: cannot open shared object file") the one
+        # time this was set explicitly, before libpq.so.5.16 itself
+        # ever got a chance to matter.
+        # Member's own permanent Postgres connection — the SAME RDS
+        # instance @@logical_id@@ itself writes rust/host's flat
+        # journal into, different database engine role (Ruby's own
+        # era/lineage schema, not rust/host's), never the real
+        # Fly-hosted Postgres this whole effort is retiring away from.
+        #
+        # GENERATOR-ONLY FIX, NOT YET SAFE TO DEPLOY — DB_HOST/DB_NAME/
+        # DB_SECRET_ARN/SESSION_SECRET_ARN/GOOGLE_OAUTH_SECRET_ID below
+        # replace the SAME `{{resolve:secretsmanager:...}}`-into-
+        # Environment.Variables shape rust/host's own main.rs (this
+        # template's own @@logical_id@@) used to have -- readable in
+        # plaintext by any read-only account principal via
+        # lambda:GetFunctionConfiguration, the exact exposure
+        # @@logical_id@@'s own comment above the Policies section
+        # documents. But THIS function's consumer (`lambda_handler.rb`)
+        # is not a file this generator writes or this repo carries --
+        # it lives in the deploying app's own domain directory (real,
+        # live example: a Sinatra app), outside this
+        # codebase entirely. Redeploying a domain with an existing
+        # `lambda_handler.rb` BEFORE that handler is updated to fetch
+        # these itself (`aws-sdk-secretsmanager`, not yet in this
+        # project's own Gemfile) breaks it: it still expects
+        # `ENV["DATABASE_URL"]`/`ENV["SESSION_SECRET"]`/
+        # `ENV["GOOGLE_CLIENT_ID"]`/`ENV["GOOGLE_CLIENT_SECRET"]`
+        # already resolved, and none of those keys exist below anymore.
+        DB_HOST: !GetAtt @@db_ref_id@@.Endpoint.Address
+        DB_NAME: @@db_name@@
+        DB_SECRET_ARN: !Sub "${@@secret_sub@@}"
+        SESSION_SECRET_ARN: !Sub "${@@web_logical_id@@SessionSecret}"@@web_webhook_env@@
+        @@web_google_oauth_env_yaml@@
+    VpcConfig:
+      SubnetIds: [!Ref @@db_id@@SubnetA, !Ref @@db_id@@SubnetB]
+      SecurityGroupIds: [!Ref @@logical_id@@SecurityGroup]
+    # LEAST-PRIVILEGE, scoped to @@logical_id@@'s own ARN specifically
+    # (SAM's own LambdaInvokePolicy template) — WebFunctionRole is
+    # otherwise SAM's bare default execution role (logging only), and
+    # had NO lambda:InvokeFunction permission at all until this: a
+    # real, live AccessDeniedException caught it, the same request
+    # that also caught the wrong-function-name bug just above
+    # (WebFunctionRole is not authorized... on resource
+    # hecks-task — this stack has never had ANY policy granting
+    # that action, so the fix isn't complete without adding one).
+    # THE SAME secretsmanager:GetSecretValue GRANTS @@logical_id@@'s
+    # own Policies section (above) needed, once this function's own
+    # `lambda_handler.rb` fetches DB_SECRET_ARN/SESSION_SECRET_ARN/
+    # GOOGLE_OAUTH_SECRET_ID itself instead of relying on a resolved
+    # Environment.Variables value -- see this Environment block's own
+    # comment for why that consumer-side change isn't in this repo.
+    Policies:
+      - LambdaInvokePolicy:
+          FunctionName: !Ref @@logical_id@@
+      - Statement:
+          - Effect: Allow
+            Action: secretsmanager:GetSecretValue
+            Resource: !Sub "${@@secret_sub@@}"
+      - Statement:
+          - Effect: Allow
+            Action: secretsmanager:GetSecretValue
+            Resource: !Sub "${@@web_logical_id@@SessionSecret}"@@web_webhook_policy@@
+      @@web_oauth_policy@@
+    # NONE, not AWS_IAM — real users need to reach sign-in over
+    # plain HTTPS, unlike @@logical_id@@'s own AWS_IAM-protected URL
+    # (this function is the ONLY thing meant to call that one).
+    FunctionUrlConfig:
+      AuthType: NONE

data/lib/hecks/projections/deploy/templates/lambda/web_google_oauth_env.tmpl

@@ -0,0 +1,12 @@
+# BY NAME, not `!Ref`/`!GetAtt` -- @@web_logical_id@@GoogleOauth
+# is deliberately NOT declared as a CloudFormation resource
+# here (would need either GenerateSecretString, which can't
+# invent a real Google client_id/secret, or a value baked
+# into this git-TRACKED template as plaintext). `make
+# sync-google-oauth` owns this secret's whole lifecycle
+# instead, straight from @@domain@@'s own gitignored
+# .env.local, outside CloudFormation entirely. GetSecretValue
+# accepts a bare name directly, no ARN needed -- same
+# generator-only caveat as DB_SECRET_ARN's own comment above.
+GOOGLE_OAUTH_SECRET_ID: @@stack_name@@-web-google-oauth
+GOOGLE_REDIRECT_URI: !Sub "${WebRedirectBaseUrl}/auth/google/callback"

data/lib/hecks/projections/deploy/templates/lambda/web_no_oauth_env.tmpl

@@ -0,0 +1,7 @@
+# GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET/GOOGLE_REDIRECT_URI
+# deliberately NOT set here — @@domain@@'s own .env.local has
+# no real GOOGLE_CLIENT_ID yet, matching Fly's own current
+# reality (its secrets list holds only
+# DATABASE_URL and SESSION_SECRET) that nobody has configured
+# OAuth for this app at all. Drop real credentials into
+# .env.local and regenerate to wire this up.

data/lib/hecks/projections/deploy/templates/lambda/web_oauth_policy.tmpl

@@ -0,0 +1,4 @@
+- Statement:
+    - Effect: Allow
+      Action: secretsmanager:GetSecretValue
+      Resource: !Sub "arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:@@stack_name@@-web-google-oauth-*"

data/lib/hecks/projections/deploy/templates/lambda/webhook_secret_resource.tmpl

@@ -0,0 +1,20 @@
+# Auto-generated, never typed or seen — the SAME
+# ManageMasterUserPassword/SessionSecret pattern above, applied to
+# `secret_env`'s own webhook secret instead (deploy_settings' own
+# `secret_env`, read far above). @@web_logical_id@@'s own
+# `lambda_handler.rb` fetches this by ARN at cold start (the
+# `@@webhook_secret_env@@_ARN` Environment variable below) and exposes
+# its plaintext under `ENV["@@webhook_secret_env@@"]` itself — the
+# SAME two-step indirection DB_SECRET_ARN/SESSION_SECRET_ARN already
+# use, and for the identical reason (this Environment block's own
+# header comment on why a resolved plaintext must never land in
+# Lambda's own configuration).
+@@web_logical_id@@WebhookSecret:
+  Type: AWS::SecretsManager::Secret
+  Properties:
+    GenerateSecretString:
+      SecretStringTemplate: '{}'
+      GenerateStringKey: value
+      PasswordLength: 64
+      ExcludePunctuation: true
+

data/lib/hecks/projections/deploy/templates/preview/alb.tmpl

@@ -0,0 +1,8 @@
+Alb:
+  Type: AWS::ElasticLoadBalancingV2::LoadBalancer
+  Properties:
+    Name: !Sub "@@alb_prefix@@-${EnvName}"
+    Scheme: internet-facing
+    Type: application
+    SecurityGroups: [!Ref AlbSecurityGroup]
+    Subnets: [!Ref OwningPublicSubnetAId, !Ref OwningPublicSubnetBId]

data/lib/hecks/projections/deploy/templates/preview/alb_security_group.tmpl

@@ -0,0 +1,11 @@
+AlbSecurityGroup:
+  Type: AWS::EC2::SecurityGroup
+  Properties:
+    VpcId: !Ref OwningVpcId
+    GroupDescription: !Sub "@@infra_name@@ preview ${EnvName} ALB - HTTP ingress from CloudFront only"
+    SecurityGroupIngress:
+      # The AWS-managed com.amazonaws.global.cloudfront.origin-facing prefix list.
+      - IpProtocol: tcp
+        FromPort: 80
+        ToPort: 80
+        SourcePrefixListId: @@prefix_list@@

data/lib/hecks/projections/deploy/templates/preview/assume_role.tmpl

@@ -0,0 +1,6 @@
+AssumeRolePolicyDocument:
+  Version: '2012-10-17'
+  Statement:
+    - Effect: Allow
+      Principal: { Service: ecs-tasks.amazonaws.com }
+      Action: sts:AssumeRole

data/lib/hecks/projections/deploy/templates/preview/base_parameters.tmpl

@@ -0,0 +1,24 @@
+EnvName:
+  Type: String
+  AllowedPattern: '^[a-z0-9]([a-z0-9-]{0,18}[a-z0-9])?$'
+  ConstraintDescription: lowercase letters, digits and hyphens, at most 20 characters, not ending in a hyphen (the ALB name limit is 32).
+DbName:
+  Type: String
+  AllowedPattern: '^[a-z][a-z0-9_]{0,62}$'
+  Description: This preview's own database on the shared instance, created by the one-shot DbInit task before the service starts.
+OwningVpcId:
+  Type: AWS::EC2::VPC::Id
+OwningSubnetAId:
+  Type: AWS::EC2::Subnet::Id
+OwningSubnetBId:
+  Type: AWS::EC2::Subnet::Id
+OwningPublicSubnetAId:
+  Type: AWS::EC2::Subnet::Id
+OwningPublicSubnetBId:
+  Type: AWS::EC2::Subnet::Id
+OwningSecurityGroupId:
+  Type: AWS::EC2::SecurityGroup::Id
+OwningDatabaseEndpoint:
+  Type: String
+OwningDatabaseSecretArn:
+  Type: String

data/lib/hecks/projections/deploy/templates/preview/cluster.tmpl

@@ -0,0 +1,4 @@
+Cluster:
+  Type: AWS::ECS::Cluster
+  Properties:
+    ClusterName: !Sub "@@prefix@@-${EnvName}"

data/lib/hecks/projections/deploy/templates/preview/container_secret.tmpl

@@ -0,0 +1,9 @@
+@@id@@:
+  Type: AWS::SecretsManager::Secret
+  Properties:
+    Description: !Sub "@@name@@ of the ${EnvName} preview's @@container@@ container."
+    GenerateSecretString:
+      SecretStringTemplate: '{}'
+      GenerateStringKey: secret
+      PasswordLength: 64
+      ExcludePunctuation: true