hecks 3.4.2 → 3.6.0

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

@@ -0,0 +1,122 @@
+	@echo "Looking up $(STACK)'s VPC/security group..."
+# stack_outputs/bastion_parameters (hecks deploy project) are the ONE
+# place these OutputKey strings and parameter names live — this eval
+# chain and the --parameter-overrides line just below are both
+# generated from the SAME table template.yaml's Outputs and
+# bastion.yaml's Parameters already read from.
+	@@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
+# ONE continuous shell invocation from here on (every line ends in
+# \, joining it to the next) — INSTANCE_ID is a SHELL variable, not
+# a Make one: a Make-level $$(eval $$(shell ...)) expands at parse
+# time, BEFORE the `aws cloudformation deploy` line above ever runs,
+# which would make INSTANCE_ID permanently empty. It can only be
+# computed here, after the bastion stack genuinely exists.
+#
+# A COMMENT LINE MUST NEVER SIT BETWEEN TWO \-CONTINUED RECIPE
+# LINES — confirmed live, the hard way: a `#`-prefixed line inserted
+# between `DB_PASS=...; \` and the line that used it silently
+# corrupted Make's own assembly of this whole block into one shell
+# script, and `DB_PASS` came out empty on the far side despite
+# printing correctly one line earlier. Every explanatory comment for
+# this whole chain belongs HERE, before it starts, same as this one —
+# never spliced into the middle of it.
+#
+# BASTION TEARDOWN IS PART OF THIS SAME CHAIN, ALL THE WAY THROUGH —
+# a prior version of this recipe ended at `exit $$BOOT_STATUS` with
+# no trailing `\`, which made Make treat the delete-stack lines
+# after it as a SEPARATE recipe line, reached only on a zero exit.
+# A failed boot (bad tunnel, bad `ruby -e` invocation, anything) left
+# the bastion stack standing forever — including a live 5432 ingress
+# rule punched into the PRODUCTION RDS security group. Teardown now
+# runs unconditionally, with BOOT_STATUS captured up front and
+# returned last, so `make mint-era`'s own exit code still reflects
+# whether era 1 actually got minted.
+#
+# `LineageManager.check!` directly below, NOT `Hecks.boot` — also
+# confirmed live (the very first real invoke: "relation
+# \"hecks_eras\" does not exist", despite this step itself
+# reporting success): `Hecks.boot` always dispatches persistence
+# through whatever the domain's OWN .world file declares
+# (`persisted_by("Heki")` for a domain that hasn't opted into
+# Postgres for local dev), by EXPLICIT design — loader.rb's own
+# comment: "persisted_by(\"PostgresEra\") is never inferred from
+# anything else." `EraCheck.check!` (what `Hecks.boot` runs) is
+# itself adapter-capability-gated on that same declaration and simply
+# no-ops for a non-lineage-capable adapter — it never touches
+# hecks_eras at all. The fix reuses the SAME loading pipeline
+# `Loader.boot` itself does (`Ports::Loading.bootstrap`/
+# `load_library`/`load_project`/`load_domain`) to build a real,
+# fully-loaded registry (bluebook + any attaches attachments),
+# then calls straight into PostgresEra's own `LineageManager.check!`
+# with THIS deploy's actual `DATABASE_URL` — bypassing the world
+# file's own adapter choice entirely, the same targeted pattern
+# spec/adapters/driven/postgres_era/lineage_spec.rb's own `check!` helper
+# already uses.
+#
+# THE WHOLE TUNNEL IS RESTARTED PER ATTEMPT, not just the boot
+# check retried through one long-lived tunnel — confirmed live,
+# the hard way: an SSM port-forwarding session can start and then
+# exit again within the first few seconds (visible in its own log
+# as a session ID that both starts AND exits before the retries
+# even finish), not merely "slow to become ready". Retrying a
+# Postgres connection five times against a tunnel process that has
+# already died is retrying against a corpse — it fails identically
+# every time, for a different reason than the one the retry was
+# built for. Each attempt below kills whatever tunnel the LAST
+# attempt opened (a no-op the first time) and opens a fresh one,
+# so a dead session gets a real replacement, not just more patience.
+#
+# DB_PASS_URLENC, DERIVED RIGHT AFTER DB_PASS BELOW, IS WHAT ACTUALLY
+# GOES INTO THE `postgres://` URL FURTHER DOWN — not DB_PASS itself.
+# RDS/Secrets-Manager-generated passwords are not guaranteed free of
+# `%`, and libpq's own connection-URI parser treats a bare `%` as an
+# invalid token (percent-encoding is the one escape libpq's URI form
+# actually documents and decodes; a raw `%` is not) -- roughly 29% of
+# 32-char generated passwords contain at least one `%`, so this was
+# silently unreachable until it wasn't. `ERB::Util.url_encode`
+# percent-encodes everything outside RFC 3986's unreserved set,
+# exactly what a URI password component needs -- a strict superset
+# of the ExcludeCharacters the Aurora path below already excludes
+# (a no-op there), and the actual fix for the plain-RDS
+# ManageMasterUserPassword path, whose generated character set this
+# template has no control over at all. This comment sits HERE,
+# before the chain starts, on purpose -- see the note further below
+# on why a comment line can never be spliced between two
+# ``-continued recipe lines.
+	@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"); \
+	BOOT_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 minting era 1 (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 $(ROOT) && DATABASE_URL="postgres://postgres:$$DB_PASS_URLENC@localhost:15432/@@db_name@@" ruby -Ilib -e 'require "hecks"; require "hecks/ports/persistence/plugins/era"; loading = Hecks::Ports::Loading.bootstrap; directory = loading.bluebook_directory(ARGV[0]); root = loading.shared_root(nil, directory); registry = Hecks::Runtime::Registry.new(root: File.dirname(directory)); Hecks.with_registry(registry) { loading.load_library; loading.load_project(root); loading.load_domain(directory) }; bluebook = registry.bluebooks[@@declared_domain_literal@@] or abort "no @@declared_domain_name@@ bluebook loaded"; current_text = Hecks::Runtime::EraCheck.source_text_for(bluebook, directory); Hecks::Adapters::PostgresEra::LineageManager.check!(registry: registry, bluebook: bluebook, current_text: current_text, settings: { database: ENV["DATABASE_URL"]@@schema_setting@@ }); db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, { database: ENV["DATABASE_URL"]@@schema_setting@@ }); lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name); (registry.bluebooks.values - [bluebook]).each { |other| other.aggregates.each { |aggregate| lineage.ensure_first_head!(aggregate.storage_name) } }; db.close; puts "booted OK — era resolution ran"' $(DOMAIN) && { BOOT_STATUS=0; break; }; \
+		BOOT_STATUS=$$?; \
+		echo "boot check attempt $$attempt/5 failed (exit $$BOOT_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. Era 1 should now be held if BOOT_STATUS was 0 — verify with hecks console or a Postgres query against hecks_eras."; \
+	exit $$BOOT_STATUS

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

@@ -0,0 +1,47 @@
+# NOT AUTOMATED YET for a Shared-mode domain — it has no RDS/VPC
+# of its own to stand a temporary bastion next to (bastion.yaml
+# itself isn't even generated here — hecks deploy project's own
+# comment on why). Minting era 1 for @@infra_name@@'s own schema
+# needs a tunnel to @@owner_domain_name@@'s ALREADY-EXISTING RDS
+# instance instead -- reuse @@owner_domain_name@@'s own deploy
+# directory's `make mint-era` machinery (or an already-open
+# tunnel to it) to run this domain's own boot against
+# `postgres://...@<tunnel-host>:<port>/@@owner_db_name@@` with
+# `schema: @@infra_name_literal@@` in LineageManager.check!'s own
+# settings -- the exact same call this target runs automatically
+# for a domain with its own dedicated instance.
+#
+# IF THIS DOMAIN VENDORS/ATTACHES ANOTHER BLUEBOOK (attaches,
+# attaches ... from: :vendor), `check!` alone leaves THAT chapter's own
+# aggregates with no snapshot table at all -- it only provisions the
+# ONE bluebook it's called with (era_resolver.rb's own `bluebook.
+# aggregates.each`), never the whole registry. Found live minting
+# a client site's own era: `Payments::Payment.Initiate` refused with
+# "relation \"payment_head_snapshot_1\" does not exist" the first
+# time this domain's own checkout route ran for real. The automated
+# (non-Shared) recipe below now does this correctly for every OTHER
+# loaded bluebook, using ONE `Lineage` keyed by THIS domain's own
+# name (never each chapter's own -- a vendored chapter's aggregates
+# share THIS domain's single `hecks_journal_@@infra_name@@` and
+# snapshot tables, they do not get a separate journal of their own).
+# Reproduce the same shape manually here: after `LineageManager.
+# check!` returns, `db = PostgresEra.connect_for(bluebook.name,
+# settings)`, `lineage = Lineage.new(db, bluebook.name)`, then for
+# every OTHER loaded bluebook's own aggregates, `lineage.
+# ensure_first_head!(aggregate.storage_name)`.
+#
+# EXIT 0, NOT 1 -- `deploy:`'s own last line (below) always chains
+# `$(MAKE) mint-era` unconditionally, even for a Shared-mode domain,
+# so a nonzero exit here used to mean a fully successful `sam
+# deploy` still left `make deploy` exiting nonzero -- confirmed
+# live: CI and any scripted caller read every Shared-mode deploy as
+# failed, which trains operators to ignore a red `make deploy` on
+# exactly the domains where a real failure most needs to stand out.
+# This step never fails at its own job (it has no automated job to
+# fail at -- it only reports that a manual step remains), so it
+# reports success and leaves the manual-step reminder in the echo
+# text above, not in the exit code. A human running `make mint-era`
+# directly still SEES the same message; they just don't get a
+# misleading "command failed" on top of it either.
+	@echo "mint-era isn't automated yet for a Shared-mode domain (database \"Shared\") -- see this target's own comment in the generated Makefile for the manual path through @@owner_domain_name@@'s own tunnel. This is NOT a failure -- exiting 0 so a genuinely successful \"make deploy\" still reports success; era-minting for this domain remains a separate manual step."; \
+	exit 0

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

@@ -0,0 +1,9 @@
+@@world_file@@'s deployed_to("AwsLambda") declares database "Shared" but no owner. Add one, e.g.:
+
+    deployed_to("AwsLambda") do
+      ...
+      database "Shared"
+      owner "Core"
+    end
+
+naming the already-deployed domain whose Postgres instance this one borrows.

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

@@ -0,0 +1,14 @@
+  #
+  # @@web_logical_id@@ is the ONE exception -- real Google OAuth token
+  # exchange (hecks's own GoogleAuthentication adapter posting to
+  # https://oauth2.googleapis.com/token) is a genuine third-party HTTPS
+  # call with no AWS PrivateLink/VPC Endpoint option (unlike
+  # lambda:InvokeFunction, above), and @@web_logical_id@@ is ALSO
+  # VPC-attached (Member's own permanent Postgres binding needs the
+  # private RDS instance directly). A real, live 15-second Lambda
+  # timeout caught this -- the token-exchange POST had nowhere to
+  # route to and just hung. @@db_id@@NatGateway below is the real,
+  # ongoing-cost fix (one NAT Gateway, one public subnet) -- opt-in,
+  # the SAME google_oauth_present signal that wires
+  # GOOGLE_CLIENT_ID/SECRET, since nothing else in this stack needs
+  # outbound internet at all.

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

@@ -0,0 +1,3 @@
+  # Real outbound internet access from here (a future external API
+  # call, say) would need a NAT Gateway added -- a real, ongoing cost
+  # this template doesn't take on until something actually needs it.

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

@@ -0,0 +1,8 @@
+# deploy's own last step below looks up @@web_logical_id@@'s
+# CURRENTLY deployed Function URL live (not tracked anywhere
+# generated) and passes it as WebRedirectBaseUrl -- see that
+# Parameter's own comment, above, for why GOOGLE_REDIRECT_URI can't
+# just be a CloudFormation intrinsic. Empty on a genuine first
+# deploy (before the Url exists at all); every deploy after that
+# finds the real, STABLE hostname (confirmed unchanged across every
+# redeploy this session) and self-heals GOOGLE_REDIRECT_URI to match.

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

@@ -0,0 +1,13 @@
+# Lambda Function URLs get a random, un-derivable hostname at
+# creation -- @@web_logical_id@@'s own GOOGLE_REDIRECT_URI can't
+# reference `!GetAtt @@web_logical_id@@Url.FunctionUrl` from inside
+# @@web_logical_id@@'s OWN Environment (that's a real circular
+# dependency CloudFormation rejects: the value doesn't exist until
+# the function+URL do). Resolved OUTSIDE the stack instead --
+# `make deploy`'s own recipe looks up the CURRENTLY deployed
+# Function URL (empty on a true first deploy, before the URL
+# exists at all) and passes it as `--parameter-overrides`; every
+# deploy after the first self-heals this correctly.
+WebRedirectBaseUrl:
+  Type: String
+  Default: ""

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

@@ -0,0 +1,33 @@
+# THE STOREHOUSE — @@owner_domain_name@@'s own live stack Outputs,
+# looked up at deploy time (Makefile's own `deploy:`/`mint-era`
+# targets, below) via the SAME `aws cloudformation describe-stacks`
+# pattern `mint-era` already used for a bastion, one stack over
+# instead of one sibling stack over. Never a CloudFormation
+# Export/ImportValue -- this codebase uses none anywhere (hecks
+# deploy project's own header on why: a live shell lookup keeps
+# this stack independently deployable/deletable, never coupled to
+# @@owner_domain_name@@'s own stack through CloudFormation itself).
+OwningVpcId:
+  Type: AWS::EC2::VPC::Id
+OwningSubnetAId:
+  Type: AWS::EC2::Subnet::Id
+OwningSubnetBId:
+  Type: AWS::EC2::Subnet::Id
+# @@owner_domain_name@@'s own Lambda security group, NOT its
+# DB-facing one -- reused whole, not copied, the same shape
+# this codebase already trusts elsewhere (a WebFunction sharing
+# its own dispatch Lambda's security group rather than minting
+# a second one), one stack over instead of one resource over.
+# @@owner_domain_name@@'s own DB security group already permits
+# ingress FROM this group (every member of it, regardless of
+# which stack minted the member -- security group references
+# match on GROUP MEMBERSHIP, not resource identity), so joining
+# it is what actually grants this Lambda access, not a new
+# ingress rule @@owner_domain_name@@'s own stack would otherwise
+# need to add.
+OwningSecurityGroupId:
+  Type: AWS::EC2::SecurityGroup::Id
+OwningDatabaseEndpoint:
+  Type: String
+OwningDatabaseSecretArn:
+  Type: String

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

@@ -0,0 +1,71 @@
+# @@web_logical_id@@'s own `pg` gem needs a native extension SAM's
+# default Ruby builder can't produce correctly: the precompiled
+# aarch64-linux binary needs GLIBC 2.29+, but 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 ever reaching the file that defines it).
+# Built once, from source, in the SAME container `sam build
+# --use-container` itself uses (its glibc, not the host's, is what
+# has to match the deployed runtime) — then cached under
+# PG_NATIVE_DIR so every later `make deploy` skips straight to the
+# fast path. Delete that directory to force a clean rebuild.
+#
+# OpenSSL is built `no-shared` and linked STATICALLY into libpq, so
+# the libpq.so this produces carries no runtime dependency on
+# whatever OpenSSL (if any) happens to already be on the Lambda
+# execution image — sidesteps the AL2 package conflict between
+# `openssl-libs` and the build image's own pre-installed
+# `openssl-snapsafe-libs` entirely, rather than fighting it.
+PG_NATIVE_DIR := @@root@@/tmp/pg-native-arm64-ruby3.2
+
+$(PG_NATIVE_DIR)/pg_ext.so:
+	@mkdir -p $(PG_NATIVE_DIR)
+	@echo "Building @@web_logical_id@@'s pg native extension from source (cached under $(PG_NATIVE_DIR) after this — a few minutes, one time only)..."
+	docker run --rm --platform linux/arm64 -v $(PG_NATIVE_DIR):/out \
+		--entrypoint /bin/bash public.ecr.aws/sam/build-ruby3.2:latest-arm64 -c ' \
+			set -e; \
+			yum install -y perl-IPC-Cmd >/dev/null; \
+			cd /tmp; \
+			curl -sL https://www.openssl.org/source/openssl-3.0.15.tar.gz | tar xz; \
+			cd openssl-3.0.15; \
+			./Configure linux-aarch64 no-shared no-tests --prefix=/tmp/openssl-install >/dev/null; \
+			make -j$$(nproc) >/dev/null; \
+			make install_sw >/dev/null; \
+			cd /tmp; \
+			curl -sL https://ftp.postgresql.org/pub/source/v16.4/postgresql-16.4.tar.gz | tar xz; \
+			cd postgresql-16.4; \
+			CPPFLAGS="-I/tmp/openssl-install/include" LDFLAGS="-L/tmp/openssl-install/lib" \
+				./configure --without-readline --without-zlib --without-icu --with-ssl=openssl --prefix=/tmp/pg-install >/dev/null; \
+			make -C src/include install >/dev/null; \
+			make -C src/interfaces/libpq -j$$(nproc) install >/dev/null; \
+			cd /tmp; \
+			gem fetch pg -v @@pg_version@@ --platform ruby >/dev/null; \
+			gem unpack pg-@@pg_version@@.gem --target=/tmp/gemsrc >/dev/null; \
+			cd /tmp/gemsrc/pg-@@pg_version@@/ext; \
+			ruby -I.. -I../lib extconf.rb --with-pg-include=/tmp/pg-install/include --with-pg-lib=/tmp/pg-install/lib >/dev/null; \
+			make >/dev/null; \
+			cp pg_ext.so /out/pg_ext.so; \
+			cp /tmp/pg-install/lib/libpq.so.5.16 /out/libpq.so.5.16; \
+		'
+
+# `find`, not a hardcoded gem-version path — survives @@domain@@'s
+# own pg version bumping in its Gemfile.lock without this Makefile
+# needing regeneration to match. libpq.so.5.16 lands beside the
+# rest of @@web_logical_id@@'s code at /var/task/lib — the ruby3.2
+# base image's OWN baked-in LD_LIBRARY_PATH default already searches
+# that exact path, so no rpath patching AND no explicit
+# LD_LIBRARY_PATH override belongs in template.yaml (setting one
+# there REPLACES the image's full default list instead of extending
+# it — a real, live "libcrypt.so.1: cannot open shared object file"
+# caught this — @@web_logical_id@@'s own Environment no longer sets
+# it at all, on purpose).
+.PHONY: patch-pg-native
+patch-pg-native: $(PG_NATIVE_DIR)/pg_ext.so
+	@PG_EXT=$$(find .aws-sam/build/@@web_logical_id@@/vendor/bundle -path "*/pg-*/lib/3.2/pg_ext.so" | head -1); \
+		test -n "$$PG_EXT" || { echo "patch-pg-native: no pg_ext.so found under .aws-sam/build/@@web_logical_id@@ — run sam build --use-container @@web_logical_id@@ first"; exit 1; }; \
+		cp $(PG_NATIVE_DIR)/pg_ext.so "$$PG_EXT"
+	@mkdir -p .aws-sam/build/@@web_logical_id@@/lib
+	cp $(PG_NATIVE_DIR)/libpq.so.5.16 .aws-sam/build/@@web_logical_id@@/lib/libpq.so.5.16
+	ln -sf libpq.so.5.16 .aws-sam/build/@@web_logical_id@@/lib/libpq.so.5
+

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

@@ -0,0 +1,8 @@
+PiiOriginAccessControl:
+  Type: AWS::CloudFront::OriginAccessControl
+  Properties:
+    OriginAccessControlConfig:
+      Name: !Sub "${AWS::StackName}-pii-oac"
+      OriginAccessControlOriginType: lambda
+      SigningBehavior: always
+      SigningProtocol: sigv4

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

@@ -0,0 +1,8 @@
+PiiLambdaInvokePermission:
+  Type: AWS::Lambda::Permission
+  Properties:
+    Action: lambda:InvokeFunctionUrl
+    FunctionName: !Ref @@fronted_logical_id@@
+    Principal: cloudfront.amazonaws.com
+    SourceArn: !Sub "arn:aws:cloudfront::${AWS::AccountId}:distribution/${PiiDistribution}"
+    FunctionUrlAuthType: @@invoke_auth_type@@

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

@@ -0,0 +1,116 @@
+PiiAccessLogsBucket:
+  Type: AWS::S3::Bucket
+  Properties:
+    # `BucketOwnerPreferred`, not the newer `BucketOwnerEnforced`
+    # default — CloudFront's own classic access-log delivery
+    # (`Logging:`, on PiiDistribution below) still authorizes itself
+    # via a canned ACL (`AccessControlTranslation` between accounts is
+    # a distinct, newer mechanism this bucket has no other account to
+    # need), which an ACLs-disabled bucket refuses outright.
+    OwnershipControls:
+      Rules:
+        - ObjectOwnership: BucketOwnerPreferred
+    AccessControl: LogDeliveryWrite
+    LifecycleConfiguration:
+      Rules:
+        - Id: ExpirePiiAccessLogs
+          Status: Enabled
+          ExpirationInDays: 365
+
+PiiResponseHeadersPolicy:
+  Type: AWS::CloudFront::ResponseHeadersPolicy
+  Properties:
+    ResponseHeadersPolicyConfig:
+      Name: !Sub "${AWS::StackName}-pii-headers"
+      SecurityHeadersConfig:
+        StrictTransportSecurity:
+          AccessControlMaxAgeSec: 63072000
+          IncludeSubdomains: true
+          Override: true
+        ContentTypeOptions:
+          Override: true
+        FrameOptions:
+          FrameOption: DENY
+          Override: true
+        ReferrerPolicy:
+          ReferrerPolicy: same-origin
+          Override: true
+        XSSProtection:
+          ModeBlock: true
+          Protection: true
+          Override: true
+
+PiiWebAcl:
+  Type: AWS::WAFv2::WebACL
+  Properties:
+    Name: !Sub "${AWS::StackName}-pii-waf"
+    Scope: CLOUDFRONT
+    DefaultAction:
+      Allow: {}
+    VisibilityConfig:
+      SampledRequestsEnabled: true
+      CloudWatchMetricsEnabled: true
+      MetricName: !Sub "${AWS::StackName}PiiWebAcl"
+    Rules:
+      - Name: AWSManagedRulesCommonRuleSet
+        Priority: 0
+        OverrideAction:
+          None: {}
+        Statement:
+          ManagedRuleGroupStatement:
+            VendorName: AWS
+            Name: AWSManagedRulesCommonRuleSet
+        VisibilityConfig:
+          SampledRequestsEnabled: true
+          CloudWatchMetricsEnabled: true
+          MetricName: !Sub "${AWS::StackName}PiiCommonRuleSet"
+      - Name: AWSManagedRulesKnownBadInputsRuleSet
+        Priority: 1
+        OverrideAction:
+          None: {}
+        Statement:
+          ManagedRuleGroupStatement:
+            VendorName: AWS
+            Name: AWSManagedRulesKnownBadInputsRuleSet
+        VisibilityConfig:
+          SampledRequestsEnabled: true
+          CloudWatchMetricsEnabled: true
+          MetricName: !Sub "${AWS::StackName}PiiKnownBadInputs"
+
+@@origin_access_control@@
+PiiDistribution:
+  Type: AWS::CloudFront::Distribution
+  Properties:
+    DistributionConfig:
+      Enabled: true
+      HttpVersion: http2
+      WebACLId: !GetAtt PiiWebAcl.Arn
+      Restrictions:
+        GeoRestriction:
+          RestrictionType: @@geo_restriction_type@@
+          Locations:@@geo_locations@@
+      Logging:
+        Bucket: !GetAtt PiiAccessLogsBucket.RegionalDomainName
+        IncludeCookies: false
+        Prefix: cloudfront/
+      Origins:
+        - Id: PiiOrigin
+          # `!Select [2, !Split ["/", ...]]` — the standard AWS-documented
+          # way to pull the bare hostname out of a Function URL's own
+          # `https://<id>.lambda-url.<region>.on.aws/` shape for use as a
+          # CustomOriginConfig DomainName, which admits no scheme or path.
+          DomainName: !Select [2, !Split ["/", !GetAtt @@fronted_logical_id@@Url.FunctionUrl]]
+          CustomOriginConfig:
+            OriginProtocolPolicy: https-only
+            OriginSSLProtocols: [TLSv1.2]
+@@oac_reference@@
+      DefaultCacheBehavior:
+        TargetOriginId: PiiOrigin
+        ViewerProtocolPolicy: redirect-to-https
+        AllowedMethods: [GET, HEAD, OPTIONS, PUT, PATCH, POST, DELETE]
+        CachedMethods: [GET, HEAD]
+        CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad
+        OriginRequestPolicyId: 216adef6-5c7f-47e4-b989-5492eafa07d3
+        ResponseHeadersPolicyId: !Ref PiiResponseHeadersPolicy
+
+@@invoke_permission@@

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

@@ -0,0 +1,30 @@
+# THE TRANSACTION-SAFETY GAP, closed for the case that actually
+# matters: `sam deploy` below is what flips this Lambda's own
+# HECKS_DOMAIN/HECKS_SCHEMA env vars live — the INSTANT it
+# completes, real traffic can hit a domain/schema combination
+# whose era history hasn't been bridged yet if THIS domain was
+# just renamed (formerly_known_as) or its schema just moved.
+# `mint-era` already bridges that (era_resolver.rb's own
+# rename_domain! path, idempotent either way) — it only ran
+# AFTER `sam deploy` before this existed, which is exactly the
+# order that left a real live window open the one time this was
+# actually run in anger (an SSM tunnel flaked mid-bridge, after
+# the Lambda had already flipped over).
+#
+# STILL RUNS AFTER TOO (unchanged, below) — this pre-check
+# cannot replace that: a domain's VERY FIRST deploy has no
+# stack, hence no RDS, hence nothing to tunnel to yet, so
+# mint-era's real first run has to stay where it always was,
+# once `sam deploy` has just created that RDS instance. This
+# only ADDS a second, EARLIER run for a domain that already has
+# a live stack (a rename or an ordinary redeploy) — cheap and
+# safe either way, since mint-era's own quiet-reboot path is a
+# no-op the moment nothing has actually changed.
+#
+# See predeploy_bridge_shell's own comment (hecks deploy project,
+# above, right before deploy_recipe_lines) for why this branches
+# on google_oauth_present at all -- the short version: adding
+# Google OAuth to an EXISTING stack would otherwise deadlock this
+# exact pre-check against outputs the upcoming sam deploy (not
+# yet run) hasn't created.
+@@predeploy_bridge_shell@@

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

@@ -0,0 +1,12 @@
+@echo "Checking whether $(STACK) already exists, and if so whether it already has Google OAuth's PublicSubnetId/BastionSubnetId outputs, before deciding whether to bridge era history now or let this deploy create them first..."
+@if aws cloudformation describe-stacks --stack-name $(STACK) >/dev/null 2>&1; then \
+	OAUTH_OUTPUTS_READY=$$(aws cloudformation describe-stacks --stack-name $(STACK) --query "Stacks[0].Outputs[?OutputKey=='PublicSubnetId'].OutputValue" --output text 2>/dev/null); \
+	if [ -z "$$OAUTH_OUTPUTS_READY" ]; then \
+		echo "Existing stack found, but Google OAuth is newly being added -- PublicSubnetId/BastionSubnetId don't exist on it yet (sam deploy, below, is what creates them); skipping the pre-deploy bridge this one time so THIS deploy can actually run. mint-era still runs once, after sam deploy, same as a genuine first deploy."; \
+	else \
+		echo "Existing stack found -- bridging era history before this deploy flips $(STACK) over, not after."; \
+		$(MAKE) mint-era || exit 1; \
+	fi; \
+else \
+	echo "No existing stack -- first deploy, nothing to bridge yet; mint-era runs once, below, after the stack (and its RDS instance) exist."; \
+fi

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

@@ -0,0 +1,7 @@
+@echo "Checking whether $(STACK) already exists, to decide whether this deploy needs to bridge era history before it flips the stack over..."
+@if aws cloudformation describe-stacks --stack-name $(STACK) >/dev/null 2>&1; then \
+	echo "Existing stack found -- bridging era history before this deploy flips $(STACK) over, not after."; \
+	$(MAKE) mint-era || exit 1; \
+else \
+	echo "No existing stack -- first deploy, nothing to bridge yet; mint-era runs once, below, after the stack (and its RDS instance) exist."; \
+fi

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

@@ -0,0 +1,93 @@
+# THE WHOLE TUNNEL IS RESTARTED PER ATTEMPT, not just probed once
+# through a single long-lived session — confirmed live, the hard
+# way: an SSM port-forwarding session can start and then exit
+# again within seconds, not merely "slow to become ready". Probing
+# the same dead tunnel five times fails identically every time,
+# for a different reason than the retry was built for. Without
+# this restart, a still-dead tunnel also doesn't just fail loudly
+# — `EXISTS_OLD`/`EXISTS_NEW` would both come back empty, which the
+# branch below reads as "neither schema exists" and reports as if
+# that were the real answer, not a connectivity failure wearing
+# its name — which is exactly why `TUNNEL_READY` gates that branch
+# explicitly rather than trusting empty results at face value.
+#
+# OLD/NEW ARE ALLOWLISTED AS BARE IDENTIFIERS, not SQL-escaped, before
+# either one reaches a psql command line: both get interpolated
+# straight into the `nspname = '...'` lookups above and the
+# `ALTER SCHEMA "..." RENAME TO "..."` below, and a schema name can't
+# be bound as a parameter the way a value can — quoting/escaping an
+# identifier is exactly the kind of thing that's easy to get subtly
+# wrong, so instead of trying, this refuses anything that isn't
+# `^[A-Za-z_][A-Za-z0-9_]*$` outright. `make` runs this recipe as an
+# operator command, not user-facing web input, but it still executes
+# against production RDS, so a typo'd or copy-pasted `OLD`/`NEW`
+# containing quotes or `;` must fail loudly here, before either
+# tunnel or query, rather than run as-is.
+#
+# `$$OLD`/`$$NEW` HERE, NOT `$(OLD)`/`$(NEW)`: this check itself has
+# to read the value without Make ever splicing its raw text into the
+# recipe line, or a value containing `;`/`"` would break out of THIS
+# line's shell command and run before the pattern match ever sees it
+# — confirmed live, the same way the tunnel-restart behavior above
+# was. `$$OLD` instead reads the real shell environment variable
+# `make` already exports for command-line-assigned vars, so the
+# value is one opaque string to the shell no matter what characters
+# it contains. Once a value's passed this gate it's provably just
+# `[A-Za-z0-9_]`, so the existing `$(OLD)`/`$(NEW)` splices further
+# below (already written before this fix, reused as-is) are safe.
+	@[ -n "$$OLD" ] && [ -n "$$NEW" ] || { echo "usage: make rename-schema OLD=<old-schema> NEW=<new-schema>"; exit 1; }
+	@echo "$$OLD" | grep -Eq '^[A-Za-z_][A-Za-z0-9_]*$$' || { echo "invalid OLD schema name -- schema names must match ^[A-Za-z_][A-Za-z0-9_]*$$, refusing to touch SQL"; exit 1; }
+	@echo "$$NEW" | grep -Eq '^[A-Za-z_][A-Za-z0-9_]*$$' || { echo "invalid NEW schema name -- schema names must match ^[A-Za-z_][A-Za-z0-9_]*$$, refusing to touch SQL"; exit 1; }
+	@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
+	@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"]'); \
+	TUNNEL_READY=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 (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; \
+		PGPASSWORD=$$DB_PASS psql -h localhost -p 15432 -U postgres -d @@db_name@@ -tAc "SELECT 1" >/dev/null 2>&1 && { TUNNEL_READY=0; break; }; \
+		echo "tunnel not carrying real traffic yet (attempt $$attempt/5) -- restarting the tunnel and retrying in 3s..."; \
+		sleep 3; \
+	done; \
+	EXISTS_OLD=$$(PGPASSWORD=$$DB_PASS psql -h localhost -p 15432 -U postgres -d @@db_name@@ -tAc "SELECT 1 FROM pg_namespace WHERE nspname = '$(OLD)'"); \
+	EXISTS_NEW=$$(PGPASSWORD=$$DB_PASS psql -h localhost -p 15432 -U postgres -d @@db_name@@ -tAc "SELECT 1 FROM pg_namespace WHERE nspname = '$(NEW)'"); \
+	if [ "$$TUNNEL_READY" != "0" ]; then \
+		echo "tunnel never carried a real connection -- aborting without touching either schema"; \
+		BOOT_STATUS=1; \
+	elif [ "$$EXISTS_NEW" = "1" ]; then \
+		echo "schema $(NEW) already exists -- already renamed, no-op"; \
+		BOOT_STATUS=0; \
+	elif [ "$$EXISTS_OLD" = "1" ]; then \
+		PGPASSWORD=$$DB_PASS psql -h localhost -p 15432 -U postgres -d @@db_name@@ -v ON_ERROR_STOP=1 -c "ALTER SCHEMA \"$(OLD)\" RENAME TO \"$(NEW)\""; \
+		BOOT_STATUS=$$?; \
+		echo "renamed schema $(OLD) to $(NEW) (exit $$BOOT_STATUS)"; \
+	else \
+		echo "neither schema $(OLD) nor $(NEW) exists on @@db_name@@ -- nothing to rename"; \
+		BOOT_STATUS=1; \
+	fi; \
+	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 $$BOOT_STATUS

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

@@ -0,0 +1,7 @@
+# NOT AUTOMATED for a Shared-mode domain, same reason mint-era
+# isn't: there is no bastion.yaml here to stand up next to (this
+# domain has no RDS/VPC of its own). This domain's own schema
+# lives inside @@owner_domain_name@@'s database — run this same
+# target from @@owner_domain_name@@'s own deploy directory instead.
+	@echo "rename-schema isn't automated for a Shared-mode domain (database \"Shared\") -- run it from @@owner_domain_name@@'s own deploy directory instead, which owns the RDS instance this domain's schema actually lives on."; \
+	exit 1

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

@@ -0,0 +1,17 @@
+# NOT `{{resolve:secretsmanager:...}}` composing
+# GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET/SESSION_SECRET
+# directly anymore -- the identical GetFunctionConfiguration
+# exposure DATABASE_URL's own comment above documents
+# applied here too. main.rs's own cold start fetches both
+# secrets itself and `set_var`s the real GOOGLE_CLIENT_ID/
+# GOOGLE_CLIENT_SECRET/SESSION_SECRET keys before anything
+# else runs -- auth.rs/web.rs still read those exact keys,
+# unchanged. GOOGLE_OAUTH_SECRET_ID is a bare NAME (`make
+# sync-google-oauth` owns @@stack_name@@-web-google-oauth's
+# whole lifecycle outside CloudFormation, straight from
+# @@domain@@'s own gitignored .env.local, never baked into
+# this generated, git-tracked template as plaintext) --
+# GetSecretValue accepts a name directly, no ARN needed.
+GOOGLE_OAUTH_SECRET_ID: @@stack_name@@-web-google-oauth
+GOOGLE_REDIRECT_URI: !Sub "${WebRedirectBaseUrl}/auth/google/callback"
+SESSION_SECRET_ARN: !Sub "${@@logical_id@@SessionSecret}"