hecks 3.11.0 → 3.13.0

data/lib/hecks/projections/deploy/box/templates/edge.mk.tmpl

@@ -0,0 +1,17 @@
+# GENERATED by hecks deploy project -- re-run it to refresh this file rather than hand-editing.
+# Included by the Makefile beside it; the aliases come from the domain's deployed_to("AwsBox")
+# block (cdn).
+
+EDGE_STACK = @@EDGE_STACK@@
+
+.PHONY: edge
+
+# Creates or updates the CloudFront edge stack in front of the box (run `make stacks` first: the
+# box's AppOriginDomain output is the distribution's origin). The certificate is never created
+# here: issue it in ACM in us-east-1, validate its DNS records, then pass its ARN.
+#   make edge CERTIFICATE_ARN=arn:aws:acm:us-east-1:<account>:certificate/<id>
+edge:
+	@test -n "$(CERTIFICATE_ARN)" || { echo "usage: make edge CERTIFICATE_ARN=arn:aws:acm:us-east-1:..." >&2; exit 1; }
+	aws cloudformation deploy --region @@REGION@@ --template-file edge.yaml --stack-name $(EDGE_STACK) \
+		--parameter-overrides CertificateArn=$(CERTIFICATE_ARN) \
+		AppOriginDomain=$$(aws cloudformation describe-stacks --region @@REGION@@ --stack-name $(BOX_STACK) --query "Stacks[0].Outputs[?OutputKey=='AppOriginDomain'].OutputValue" --output text)

data/lib/hecks/projections/deploy/box/templates/edge.yaml.tmpl

@@ -0,0 +1,65 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >
+  The CloudFront edge of @@STACK@@: one distribution in front of the app box. Its only origin is the
+  box's public DNS name over plain http on port 80, and every request to it carries the origin secret
+  header the box's proxy checks. Nothing is cached: the origin decides what a response means.
+
+Parameters:
+  AppOriginDomain:
+    Type: String
+    AllowedPattern: ".+"
+    ConstraintDescription: the box stack's AppOriginDomain output
+    Description: DNS name of the app box, the distribution's only origin.
+  CertificateArn:
+    Type: String
+    AllowedPattern: "arn:aws:acm:us-east-1:.+"
+    ConstraintDescription: an ACM certificate in us-east-1 that covers every alias
+    Description: >
+      An issued ACM certificate in us-east-1 that covers every name in DomainNames. It is never created
+      here: DNS validation is a step an operator performs.
+  DomainNames:
+    Type: CommaDelimitedList
+    Default: "@@ALIASES@@"
+    Description: The host names the distribution answers on.
+
+Resources:
+  Distribution:
+    Type: AWS::CloudFront::Distribution
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      DistributionConfig:
+        Enabled: true
+        HttpVersion: http2
+        IPV6Enabled: true
+        Aliases: !Ref DomainNames
+        ViewerCertificate:
+          AcmCertificateArn: !Ref CertificateArn
+          SslSupportMethod: sni-only
+          MinimumProtocolVersion: TLSv1.2_2021
+        Origins:
+          - Id: BoxOrigin
+            DomainName: !Ref AppOriginDomain
+            OriginCustomHeaders:
+              # Resolved by CloudFormation from Secrets Manager when the stack deploys, so the value
+              # never appears on a command line or in this file.
+              - HeaderName: @@ORIGIN_HEADER@@
+                HeaderValue: "{{resolve:secretsmanager:@@ORIGIN_SECRET@@:SecretString}}"
+            CustomOriginConfig:
+              OriginProtocolPolicy: http-only
+              OriginSSLProtocols: [TLSv1.2]
+        DefaultCacheBehavior:
+          TargetOriginId: BoxOrigin
+          ViewerProtocolPolicy: redirect-to-https
+          AllowedMethods: [GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE]
+          CachedMethods: [GET, HEAD]
+          Compress: true
+          CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad # Managed-CachingDisabled
+          OriginRequestPolicyId: 216adef6-5c7f-47e4-b989-5492eafa07d3 # Managed-AllViewer
+
+Outputs:
+  DistributionId:
+    Value: !Ref Distribution
+  DistributionDomainName:
+    Description: Point each alias's DNS record (CNAME or alias) at this name.
+    Value: !GetAtt Distribution.DomainName

data/lib/hecks/projections/deploy/box/templates/log-group.yaml.tmpl

@@ -0,0 +1,12 @@
+  # Every container's log, one stream per service. The group is made here and not by Docker
+  # (awslogs-create-group is "false"), so the role below needs no right to create groups, and the
+  # retention is a declaration. A production group outlives the stack: the evidence a container
+  # wrote must not go with a deleted stack.
+  BoxLogGroup:
+    Type: AWS::Logs::LogGroup
+    DeletionPolicy: !If [IsProduction, Retain, Delete]
+    UpdateReplacePolicy: !If [IsProduction, Retain, Delete]
+    Properties:
+      LogGroupName: @@LOG_GROUP@@
+      RetentionInDays: @@RETENTION_DAYS@@
+

data/lib/hecks/projections/deploy/box/templates/log-policy.yaml.tmpl

@@ -0,0 +1,7 @@
+        - PolicyName: write-logs
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: [logs:CreateLogStream, logs:PutLogEvents, logs:DescribeLogStreams]
+                Resource: !GetAtt BoxLogGroup.Arn

data/lib/hecks/projections/deploy/box/templates/render-compose-taskdef.sh.tmpl

@@ -13,6 +13,7 @@
 # When the world names origin_env, the named origin secret is compared with those variables in the
 # task definition and the render refuses on any difference (Caddy checks the CDN's header against
 # the secret; the containers check it against their own copy). Values are never printed.
+@@COMPOSE_LOG_NOTE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 DB_HOST=${1:?rds endpoint}
@@ -36,7 +37,7 @@ if [ -n "$ORIGIN_ENV" ]; then
 fi
 
 jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
-  def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
+  @@LOG_DEF@@
   def env(c): ((c.environment // []) | map({(.name): .value}) | add // {})
     | (if has("DB_HOST") then .DB_HOST = $host | .DB_SECRET_ARN = $secret else . end);
   . as $in
@@ -44,16 +45,16 @@ jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
       ($in.services | with_entries(.value |= (. as $s
         | ($def | map(select(.name == $s.name)) | first) as $c
         | if $c == null then error("task definition has no container named " + $s.name) else
-            {image: $c.image, network_mode: "host", restart: "unless-stopped", logging: log,
+            {image: $c.image, network_mode: "host", restart: "unless-stopped", logging: @@LOG_SERVICE@@,
              environment: ({PORT: ($s.port | tostring)} + env($c))}
             + (if (($c.secrets // []) | length) > 0 then {env_file: [($s.name + ".secrets.env")]} else {} end)
           end)))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
-                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
                  + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
       + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
                   command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: log}} else {} end))}' \
+                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
   "$HERE/services.json" > compose.json
 
 jq --argjson def "$DEF" '. as $in

data/lib/hecks/projections/deploy/box/templates/render-compose.sh.tmpl

@@ -6,6 +6,7 @@
 # Tags default to "latest". Every container gets DB_HOST, DB_NAME, DB_SECRET_ARN and PORT, and runs on the
 # box's own network, so the proxy reaches each one on 127.0.0.1:<port>. Secrets named in services.json
 # are written to secrets.json for fetch-secrets.sh to resolve on the box.
+@@COMPOSE_LOG_NOTE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 DB_HOST=${1:?rds endpoint}
@@ -18,20 +19,20 @@ ECR="$ACCOUNT.dkr.ecr.$REGION.amazonaws.com"
 TAGS=$(printf '%s\n' "$@" | jq -R 'select(length > 0) | split("=") | {(.[0]): .[1]}' | jq -s 'add // {}')
 
 jq --arg ecr "$ECR" --argjson tags "$TAGS" --arg host "$DB_HOST" --arg secret "$DB_SECRET" --arg db "@@DB_NAME@@" '
-  def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
+  @@LOG_DEF@@
   . as $in
   | {services: (
       ($in.services | with_entries(.value |= (
         {image: ($ecr + "/" + .repository + ":" + ($tags[.name] // "latest")),
-         network_mode: "host", restart: "unless-stopped", logging: log,
+         network_mode: "host", restart: "unless-stopped", logging: @@LOG_SERVICE@@,
          environment: ({PORT: (.port | tostring), DB_HOST: $host, DB_NAME: $db, DB_SECRET_ARN: $secret} + .env)}
         + (if (.secrets | length) > 0 then {env_file: [(.name + ".secrets.env")]} else {} end))))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
-                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
                  + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
       + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
                   command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: log}} else {} end))}' \
+                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
   "$HERE/services.json" > compose.json
 
 jq '. as $in

data/lib/hecks/projections/deploy/box.rb

@@ -5,10 +5,12 @@ require_relative "box/hosting"
 require_relative "box/roll_recipe"
 require_relative "box/caddy"
 require_relative "box/access"
+require_relative "box/logging"
 require_relative "box/stack_yaml"
 require_relative "box/compose"
 require_relative "box/shared_database"
 require_relative "box/roll_scripts"
+require_relative "box/edge"
 
 module Hecks
   module Projections
@@ -21,10 +23,12 @@ module Hecks
         extend Projector::Target
         extend Caddy
         extend Access
+        extend Logging
         extend StackYaml
         extend Compose
         extend SharedDatabase
         extend RollScripts
+        extend Edge
 
         projects_as :aws_box, needs_world: true, emits: :files
 
@@ -123,7 +127,15 @@ module Hecks
             volume_gb: { value: settings.fetch(:volume_gb, 30) },
             database_class: { value: settings.fetch(:database_class, "db.t4g.small") },
             storage_gb: { value: settings.fetch(:storage_gb, 20) }
-          }
+          }.merge(cdn_arguments(settings[:cdn]))
+        end
+
+        # @param cdn [Hash{Symbol => Object}, nil] the world's `cdn` setting
+        # @return [Hash{Symbol => Array}] the `cdn_aliases` argument, or nothing without a `cdn`
+        def cdn_arguments(cdn)
+          return {} unless cdn.is_a?(Hash) && cdn[:aliases].is_a?(Array)
+
+          { cdn_aliases: cdn[:aliases].map { |name| { value: name } } }
         end
 
         # @param plan [Settings::Plan] the resolved settings
@@ -136,8 +148,8 @@ module Hecks
             "render-compose.sh" => render_compose_sh(plan, region),
             "fetch-secrets.sh" => File.read(File.join(TEMPLATE_DIR, "fetch-secrets.sh")),
             "deploy-box.sh" => deploy_box_sh(plan, region),
-            "Makefile" => makefile(plan)
-          }.merge(database_files(plan)).merge(migration_files(plan))
+            "Makefile" => makefile(plan, region)
+          }.merge(database_files(plan)).merge(migration_files(plan)).merge(edge_files(plan, region))
             .then { |files| Hosting.extend_files(files, plan: plan, region: region) }
         end
 

data/lib/hecks/projections/deploy/fargate/cdn/lines.rb

@@ -13,7 +13,8 @@ module Hecks
             #   (`:origin`,
             #   `:path` for an item, `:viewer_protocol`, `:methods`, `:compress`, `:cache_policy`,
             #   `:origin_request_policy`), and optionally `:response_headers_policy`, each policy as
-            #   `[id_or_intrinsic, comment_or_nil]`
+            #   `[id_or_intrinsic, comment_or_nil]`, and `:edge_function`, the logical id of a
+            #   viewer-request function
             # @param base [String] the indentation of `key`, or of the list item's dash
             # @return [Array<String>] the lines
             def behavior_lines(key, entry, base)
@@ -91,6 +92,16 @@ module Hecks
               lines << "#{pad}Compress: #{entry[:compress]}" if entry.key?(:compress)
               lines << policy_line(pad, "CachePolicyId", entry[:cache_policy])
               lines.concat(optional_policy_lines(entry, pad))
+              lines.concat(function_lines(entry, pad))
+            end
+
+            # The viewer-request function a behaviour names (`:edge_function`, the logical id of an
+            # `AWS::CloudFront::Function` in the same template), if any.
+            def function_lines(entry, pad)
+              return [] unless entry[:edge_function]
+
+              ["#{pad}FunctionAssociations:", "#{pad}  - EventType: viewer-request",
+               "#{pad}    FunctionARN: !GetAtt #{entry[:edge_function]}.FunctionARN"]
             end
 
             def optional_policy_lines(entry, pad)

data/lib/hecks/projections/site/admin_cms/templates/membership.rb

@@ -15,10 +15,12 @@ module Hecks
               // Signing in (endpoints/sso.ts) proved the person was admitted then; this asks again, so that
               // disabling or removing someone locks them out on their next request, not when their session runs out.
               //
-              // The question is the host's own account route, which answers only for a person who holds a role
-              // and is not disabled, asked with a short account token signed by the secret the host checks (the
-              // content system's AUTH_SECRET is the host's SESSION_SECRET). The answer is remembered for a minute
-              // per email so every admin request does not cost a round trip.
+              // The question is the host's members list, which the host answers (403) only to a person holding
+              // one of the admin roles, and the list's own row for the caller must hold such a role and not be
+              // disabled. It is asked with a short account token signed by the secret the host checks (the content
+              // system's AUTH_SECRET is the host's SESSION_SECRET). The answer is remembered for a minute per
+              // email so every admin request does not cost a round trip. Being admitted to the site is not enough:
+              // a member with no admin role is refused here, as the site's own admin gate refuses them.
               import { accountToken, resolveAccountCookieName } from "@hecks/client";
 
               const DEFAULT_URL = __HOST_DEFAULT__;
@@ -38,7 +40,7 @@ module Hecks
 
               export interface MembershipOptions {
                 url?: string;
-                /** The host route asked: the account route (any admitted person) by default, the members list for admin roles only. */
+                /** The host route asked: the account route (any admitted person) by default; `adminCheck` asks the members list, for admin roles only. */
                 path?: string;
                 /** Decides from the host's answer; the default is any 2xx. */
                 accept?: (res: Response, email: string) => Promise<boolean>;
@@ -83,8 +85,6 @@ module Hecks
                 };
               }
 
-              export const membership = membershipCheck();
-
               /** The roles the host's own admin gate passes. */
               export const ADMIN_ROLES = __ROLES__;
 
@@ -106,6 +106,9 @@ module Hecks
                   path: __MEMBERS_PATH__,
                   accept: async (res, email) => holdsAdminRole(await res.json().catch(() => null), email),
                 });
+
+              /** The check the sign-in endpoint and the session strategy use: admin roles only, never a plain member. */
+              export const membership = adminCheck();
             TS
           end
         end

data/lib/hecks/projections/site/edge/behaviours.rb

@@ -10,7 +10,8 @@ module Hecks
         # compression give it. A route needs none of its own when the behaviour that would match its
         # path anyway (the nearest broader route's, else the default one) is the same. The rest keep
         # the order the table declares, which is the order CloudFront matches in, and a route that
-        # a broader, different one before it would shadow is refused.
+        # a broader, different one before it would shadow is refused. The edge function a route
+        # names is part of its behaviour, so a route is folded only into one that names the same.
         class Behaviours
           # The default behaviour's path: the row that holds the settings of everything else.
           DEFAULT_PATH = "/*"
@@ -58,11 +59,14 @@ module Hecks
             policy = @edge.policy(row.cache, row.origin)
             {
               path: pattern, origin: @edge.upstream(row.origin).id, methods: methods([row]),
-              viewer_protocol: protocol(row), compress: row.compress,
-              cache_policy: Checks.resolve(policy.cache),
-              origin_request_policy: reference(policy.origin_request),
-              response_headers_policy: reference(policy.response_headers)
-            }
+              viewer_protocol: protocol(row), compress: row.compress
+            }.merge(policies(policy)).merge(row.edge ? { edge_function: row.edge } : {})
+          end
+
+          def policies(policy)
+            { cache_policy:            Checks.resolve(policy.cache),
+              origin_request_policy:   reference(policy.origin_request),
+              response_headers_policy: reference(policy.response_headers) }
           end
 
           def reference(text) = text.nil? || text == "none" ? nil : Checks.resolve(text)

data/lib/hecks/projections/site/edge/checks.rb

@@ -2,6 +2,7 @@
 
 require_relative "findings"
 require_relative "route_checks"
+require_relative "function_checks"
 
 module Hecks
   module Projections
@@ -47,6 +48,7 @@ module Hecks
             check_policies
             check_upstreams
             RouteChecks.new(@edge, @rows, @vocabulary, @problems).call
+            FunctionChecks.new(@edge, @rows, @vocabulary, @problems).call
           end
 
           private

data/lib/hecks/projections/site/edge/function_checks.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "findings"
+require_relative "function_code"
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # The part of the edge checks that reads the `EdgeFunction` rows and the routes that name
+        # them: each row is well formed and safe to write into a function, each route names a row
+        # that exists, and no row is left that nothing names.
+        class FunctionChecks
+          include Findings
+
+          # The longest logical id a function takes; the name it is given in the account adds the
+          # stack name, and CloudFront allows 64 characters in all.
+          NAME_LIMIT = 40
+
+          # @param edge [Edge] the edge being read, its rows set
+          # @param rows [Array<Table::Row>] the route table's rows
+          # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(edge, rows, vocabulary, problems)
+            @edge = edge
+            @rows = rows
+            @vocabulary = vocabulary
+            @problems = problems
+          end
+
+          # @return [void]
+          def call
+            @edge.functions.each { |function| check_function(function) }
+            repeated(@edge.functions.map(&:name), "EdgeFunction", &:itself)
+            check_derived_names
+            check_routes
+            check_unused
+          end
+
+          private
+
+          def check_function(function)
+            label = "EdgeFunction #{function.name}"
+            check_name(label, function)
+            member_of(label, "kind", function.kind, :edge_function_kind)
+            check_host(label, "host", function.host)
+            function.alias_list.each { |host| check_alias(label, function, host) }
+            check_paths(label, function)
+          end
+
+          # Two logical ids that differ only in case would be given one function name.
+          def check_derived_names
+            names = @edge.functions.map { |function| function.name.to_s }.uniq
+            names.group_by { |name| FunctionCode.kebab(name) }.each do |kebab, together|
+              problem("EdgeFunction", "#{together.join(" and ")} would both be named #{kebab}") if together.size > 1
+            end
+          end
+
+          def check_name(label, function)
+            name = function.name.to_s
+            problem(label, "is not a logical id") unless Checks::LOGICAL_ID.match?(name)
+            problem(label, "is longer than #{NAME_LIMIT} characters") if name.size > NAME_LIMIT
+          end
+
+          def check_host(label, field, host)
+            return if FunctionCode.host?(host)
+
+            problem(label, "has #{field} #{host.inspect}; #{field == "alias" ? "an" : "a"} #{field} is a lowercase hostname " \
+                           "such as app.example.test")
+          end
+
+          def check_alias(label, function, host)
+            check_host(label, "alias", host)
+            problem(label, "has alias #{host}, which is its host; an alias is another host") if host == function.host
+          end
+
+          def check_paths(label, function)
+            problem(label, "needs at least one path to watch") if function.path_list.empty?
+            function.path_list.each do |path|
+              next if FunctionCode.path?(path)
+
+              problem(label, "has path #{path.inspect}; a path is exact, starts with / and holds letters, digits and . _ ~ - /")
+            end
+          end
+
+          # Every `edge:` names a row, and a route the CDN never sees has no edge to run it.
+          def check_routes
+            @rows.select(&:edge).each do |row|
+              problem(row.path, "names edge #{row.edge}, which no EdgeFunction declares") unless @edge.function(row.edge)
+              problem(row.path, "names edge #{row.edge} and has cdn false; the edge never sees it") unless row.cdn
+            end
+          end
+
+          def check_unused
+            named = @rows.select(&:edge).map(&:edge)
+            @edge.functions.reject { |function| named.include?(function.name) }.each do |function|
+              problem("EdgeFunction #{function.name}", "is named by no route; remove the row or add edge: to a route")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge/function_code.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # The CloudFront function resource of a `redirect_host` row, and the JavaScript in it.
+        #
+        # The code is a fixed template (`redirect_host.js.tmpl`) with three values filled in: the
+        # canonical host, the alias hosts and the watched paths. A value is never escaped. One
+        # outside the strict shape of a lowercase hostname, or of a path made of unreserved
+        # characters, is refused, so no value can end a JavaScript string, a YAML block or a
+        # CloudFormation expression. The checks refuse such a row when it is read, and `code`
+        # refuses again, since it is the last step before the text is written.
+        module FunctionCode
+          # A lowercase hostname of at least two labels, as the host header is compared after
+          # lowercasing.
+          HOST = /\A([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}\z/
+
+          # A path of unreserved characters and slashes; no query, no percent escape, no quote.
+          PATH = %r{\A/[A-Za-z0-9._~/-]*\z}
+
+          # The longest hostname and path a function takes.
+          HOST_LIMIT = 253
+          PATH_LIMIT = 200
+
+          TEMPLATE = File.join(__dir__, "redirect_host.js.tmpl")
+          PLACEHOLDER = /__(CANONICAL|ALIASES|WATCHED)__/
+
+          module_function
+
+          # @param text [String] a candidate hostname
+          # @return [Boolean] whether it may be written into a function
+          def host?(text) = text.is_a?(String) && text.size <= HOST_LIMIT && HOST.match?(text)
+
+          # @param text [String] a candidate path
+          # @return [Boolean] whether it may be written into a function
+          def path?(text) = text.is_a?(String) && text.size <= PATH_LIMIT && PATH.match?(text)
+
+          # @param function [Edge::Function] a `redirect_host` row
+          # @return [String] the function's JavaScript, ending in a newline
+          # @raise [ArgumentError] when a host or path is outside the strict shapes
+          def code(function)
+            ensure_safe(function)
+            values = { "CANONICAL" => function.host, "ALIASES" => function.alias_list, "WATCHED" => function.path_list }
+            File.read(TEMPLATE).gsub(PLACEHOLDER) { JSON.generate(values.fetch(Regexp.last_match(1))) }
+          end
+
+          # @param name [String] a function's logical id
+          # @return [String] the hyphenated name the function carries, such as `host-redirect`
+          def kebab(name) = name.gsub(/([a-z0-9])([A-Z])/, '\1-\2').downcase
+
+          # @param function [Edge::Function] a `redirect_host` row
+          # @return [String] the resource, from the left margin, ending in a newline
+          def resource(function)
+            [
+              "#{function.name}:", "  Type: AWS::CloudFront::Function", "  Properties:",
+              "    Name: !Sub \"${AWS::StackName}-#{kebab(function.name)}\"", "    AutoPublish: true",
+              "    FunctionConfig:", "      Comment: Redirect the watched paths from an alias to the canonical host",
+              "      Runtime: cloudfront-js-2.0", "    FunctionCode: |",
+              *code(function).each_line.map { |line| line.strip.empty? ? "" : "      #{line.chomp}" }
+            ].join("\n") << "\n"
+          end
+
+          def ensure_safe(function)
+            raise ArgumentError, "EdgeFunction #{function.name} has no path to watch" if function.path_list.empty?
+
+            bad = unsafe_values(function)
+            return if bad.empty?
+
+            raise ArgumentError, "EdgeFunction #{function.name} has values outside the hostname and path shapes: " \
+                                 "#{bad.map(&:inspect).join(", ")}"
+          end
+
+          def unsafe_values(function)
+            [function.host, *function.alias_list].reject { |host| host?(host) } +
+              function.path_list.reject { |path| path?(path) }
+          end
+          private_class_method :ensure_safe, :unsafe_values
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge/redirect_host.js.tmpl

@@ -0,0 +1,65 @@
+function handler(event) {
+  var request = event.request;
+  var canonical = __CANONICAL__;
+  var aliases = __ALIASES__;
+  var watched = __WATCHED__;
+  var header = request.headers.host;
+  var host = header && header.value ? header.value.toLowerCase().replace(/:\d+$/, "") : "";
+  var reads = request.method === "GET" || request.method === "HEAD";
+  if (!reads || watched.indexOf(request.uri) < 0) { return request; }
+  if (host === canonical || aliases.indexOf(host) < 0) { return request; }
+  var parts = [];
+  Object.keys(request.querystring).forEach(function (key) {
+    var entry = request.querystring[key];
+    var values = entry.multiValue ? entry.multiValue.map(function (item) { return item.value; }) : [entry.value];
+    values.forEach(function (value) {
+      var name = encode(key);
+      parts.push(value === "" || value === undefined ? name : name + "=" + encode(value));
+    });
+  });
+  var query = parts.length ? "?" + parts.join("&") : "";
+  return {
+    statusCode: 302,
+    statusDescription: "Found",
+    headers: {
+      location: { value: "https://" + canonical + request.uri + query },
+      "cache-control": { value: "no-store" }
+    }
+  };
+}
+
+// Percent-encodes what cannot stand in a query string and keeps what is already encoded, so the
+// location header carries no space, control character, "&" or "#" whether the runtime hands over
+// the raw text or the decoded one. It walks the text one UTF-16 unit at a time and pairs the
+// surrogates itself (a lone one becomes U+FFFD), because CloudFront's regex engine refuses a
+// pattern that names a surrogate code point and fails the whole function at compile time.
+var SAFE = /[A-Za-z0-9\-._~!$'()*,;:@\/?+]/;
+var HEX = /^[0-9A-Fa-f]{2}$/;
+var REPLACEMENT = "%EF%BF%BD";
+
+function encode(text) {
+  var input = String(text);
+  var output = "";
+  var index = 0;
+  while (index < input.length) {
+    var unit = input.charAt(index);
+    var code = input.charCodeAt(index);
+    index += 1;
+    if (code >= 55296 && code <= 56319) {
+      var next = index < input.length ? input.charCodeAt(index) : 0;
+      if (next >= 56320 && next <= 57343) {
+        output += encodeURIComponent(unit + input.charAt(index));
+        index += 1;
+      } else {
+        output += REPLACEMENT;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      output += REPLACEMENT;
+    } else if (unit === "%") {
+      output += HEX.test(input.substr(index, 2)) ? unit : "%25";
+    } else {
+      output += SAFE.test(unit) ? unit : encodeURIComponent(unit);
+    }
+  }
+  return output;
+}