hecks 3.4.2 → 3.5.0

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

@@ -2,6 +2,13 @@
 # Roll @@STACK@@'s app box: render the compose files, push them over SSM, start the containers and check
 # them. Exits non-zero if the roll fails or the box does not answer as expected.
 #
+# Exit codes (the ones `hecks deploy box_roll.run` names; a step that fails under `set -e` ends with its
+# own status, 1 from bash and 254/255 from the aws CLI):
+#   0   the roll succeeded and the box answered healthy
+#   40  the box stack has no instance
+#   41  the roll did not succeed on the box
+#   42  the roll succeeded but the box is not healthy after it
+#
 @@USAGE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
@@ -14,7 +21,7 @@ out() { aws cloudformation describe-stacks --stack-name "$1" --query "Stacks[0].
 BOX=$(out "$BOX_STACK" InstanceId)
 DB_HOST=$(out "$RDS_STACK" DbEndpoint)
 DB_SECRET=$(out "$RDS_STACK" DbSecretArn)
-[ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 1; }
+[ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 40; }
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
 
 WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
@@ -68,7 +75,7 @@ ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$
    executionTimeout: ["900"]}')
 
 echo "==> rolling $BOX_STACK ($BOX) at $(date -u +%H:%M:%SZ)"
-run_on_box "$ROLL" || { echo "==> the roll did not succeed" >&2; exit 1; }
+run_on_box "$ROLL" || { echo "==> the roll did not succeed" >&2; exit 41; }
 
 echo "==> checking the box"
 CHECK=$(cat <<'CHECK_EOF'
@@ -81,5 +88,5 @@ if [ -z "$DOWN" ]; then echo "ok   every container is up"; else echo "FAIL conta
 CHECK_EOF
 )
 CHECK_JSON=$(jq -n --arg c "$(printf '%s' "$CHECK" | base64 | tr -d '\n')" '{commands: ["echo \($c) | base64 -d | bash"]}')
-run_on_box "$CHECK_JSON" || { echo "==> the box is NOT healthy after the roll" >&2; exit 1; }
+run_on_box "$CHECK_JSON" || { echo "==> the box is NOT healthy after the roll" >&2; exit 42; }
 echo "==> box roll done ($(date -u +%H:%M:%SZ))"

data/lib/hecks/projections/deploy/box/templates/deploy-service.services-roll.part

@@ -2,7 +2,7 @@
 # container runs now, read from the box's own Compose file, so rolling one service leaves the rest alone.
 BOX_ID="$(aws cloudformation describe-stacks --stack-name "$BOX_STACK" --region "$REGION" \
   --query "Stacks[0].Outputs[?OutputKey=='InstanceId'].OutputValue" --output text)"
-[ -n "$BOX_ID" ] && [ "$BOX_ID" != None ] || { echo "no instance in stack ${BOX_STACK}" >&2; exit 1; }
+[ -n "$BOX_ID" ] && [ "$BOX_ID" != None ] || { echo "no instance in stack ${BOX_STACK}" >&2; exit 33; }
 
 echo "==> reading the tags the box runs now"
 READ_JSON="$(jq -n --arg c "cat ${BOX_DIR}/compose.json 2>/dev/null || echo '{}'" '{commands: [$c]}')"
@@ -14,7 +14,7 @@ for _ in $(seq 1 30); do
     --query Status --output text 2>/dev/null || echo Pending)"
   [ "$state" != InProgress ] && [ "$state" != Pending ] && break
 done
-[ "$state" = Success ] || { echo "could not read the box's Compose file (${state}); nothing was rolled" >&2; exit 1; }
+[ "$state" = Success ] || { echo "could not read the box's Compose file (${state}); nothing was rolled" >&2; exit 32; }
 aws ssm get-command-invocation --command-id "$COMMAND_ID" --instance-id "$BOX_ID" --region "$REGION" \
   --query StandardOutputContent --output text > "${SCRATCH_DIR}/compose.json"
 

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

@@ -14,13 +14,24 @@
 @@MODE_SUMMARY@@
 #
 # It ends with smoke-after-deploy.sh, whose own exit codes (20-23) are distinct from a failed deploy
-# step's. SKIP_POST_DEPLOY_SMOKE=1 skips it.
+# step's. SKIP_POST_DEPLOY_SMOKE=1 skips it. `hecks deploy service_roll.run` runs this script with
+# SMOKE_BY_COMMAND=1, which ends after the roll and leaves the smoke to the smoke_run.run its policy requests.
+#
+# Exit codes (the ones `service_roll.run` names; a step that fails under `set -e` ends with its own
+# status, 1 from bash and 254/255 from the aws CLI):
+#   2   unknown service
+#   30  EXISTING_TAG is not in ECR              31  the fresh tag is already in ECR
+#   32  the box's Compose file is unreadable    33  the box stack has no instance
+#   34  the stack has no parameter for the container   35  the stack update failed or did not settle
+#   36  a parameter other than the container's changed  37  the task definition lacks the pushed image
+#   38  the task definition has no such container      40-42  deploy-box.sh's own
 #
 # Environment:
 #   LOCAL_IMAGE               local image to push, default <ecr repository>:latest
 #   EXISTING_TAG              redeploy this tag from ECR instead of building and pushing
 #   SETTLE_TIMEOUT_SECS       default 1200, how long to wait for a stack update
 #   SKIP_POST_DEPLOY_SMOKE=1  passed through to smoke-after-deploy.sh
+#   SMOKE_BY_COMMAND=1        end after the roll and print `rolled taskdef=<td> tag=<tag>`; the caller smokes
 set -euo pipefail
 
 @@SETTINGS@@
@@ -49,12 +60,12 @@ if [ -n "${EXISTING_TAG:-}" ]; then
   echo "==> reusing ${IMAGE_URI} (no push)"
   aws ecr describe-images --repository-name "$ECR_REPOSITORY" --region "$REGION" \
     --image-ids "imageTag=${TAG}" --query 'imageDetails[0].imageTags' --output text > /dev/null \
-    || { echo "tag ${TAG} is not in ECR" >&2; exit 1; }
+    || { echo "tag ${TAG} is not in ECR" >&2; exit 30; }
 else
   if aws ecr describe-images --repository-name "$ECR_REPOSITORY" --region "$REGION" \
       --image-ids "imageTag=${TAG}" > /dev/null 2>&1; then
     echo "tag ${TAG} is already in ECR; a tag is never reused. Run again." >&2
-    exit 1
+    exit 31
   fi
   echo "==> tagging ${LOCAL_IMAGE} as ${IMAGE_URI}"
   docker tag "$LOCAL_IMAGE" "$IMAGE_URI"
@@ -74,6 +85,7 @@ fi
 
 @@ROLL_STEPS@@
 
-# The deploy itself is done. End with the smoke, which reports separately.
+# The deploy itself is done. End with the smoke, which reports separately, unless the caller runs it.
 echo "==> deploy succeeded"
+[ -z "${SMOKE_BY_COMMAND:-}" ] || { echo "==> rolled taskdef=${TASKDEF:-} tag=${TAG}"; exit 0; }
 bash ./smoke-after-deploy.sh

data/lib/hecks/projections/deploy/box/templates/deploy-service.taskdef-roll.part

@@ -17,7 +17,7 @@ for key in $ALL_PARAM_KEYS; do
 done
 if [ "$found" != "1" ]; then
   echo "stack ${IMAGE_STACK} has no parameter named ${CFN_PARAM_KEY}; the image was pushed but nothing was rolled" >&2
-  exit 1
+  exit 34
 fi
 
 if UPDATE_OUT="$(aws cloudformation update-stack --stack-name "$IMAGE_STACK" --region "$REGION" \
@@ -32,11 +32,11 @@ if UPDATE_OUT="$(aws cloudformation update-stack --stack-name "$IMAGE_STACK" --r
       UPDATE_COMPLETE) echo "    -> ${stack_status}"; break ;;
       *ROLLBACK*|*FAILED*)
         echo "    -> ${stack_status}: the stack update failed, investigate before rolling anything" >&2
-        exit 1 ;;
+        exit 35 ;;
     esac
     if timed_out "$started"; then
       echo "==> the stack update did not settle within ${SETTLE_TIMEOUT_SECS}s (last: ${stack_status})" >&2
-      exit 1
+      exit 35
     fi
     sleep 10
   done
@@ -44,7 +44,7 @@ elif echo "$UPDATE_OUT" | grep -q "No updates are to be performed"; then
   echo "    -> the stack already has ${TAG}; nothing to update"
 else
   echo "$UPDATE_OUT" >&2
-  exit 1
+  exit 35
 fi
 
 echo "==> checking that only ${CFN_PARAM_KEY} changed"
@@ -56,7 +56,7 @@ CHANGED="$(jq -rn --slurpfile before "${SCRATCH_DIR}/params-before.json" --slurp
 NOW="$(jq -r --arg k "$CFN_PARAM_KEY" '.[] | select(.k == $k) | .v' "${SCRATCH_DIR}/params-after.json")"
 if [ "$NOW" != "$TAG" ] || { [ -n "$CHANGED" ] && [ "$CHANGED" != "$CFN_PARAM_KEY" ]; }; then
   echo "expected only ${CFN_PARAM_KEY} to change to ${TAG}; it is ${NOW} and changed: ${CHANGED:-nothing}" >&2
-  exit 1
+  exit 36
 fi
 echo "    -> ${CFN_PARAM_KEY} is ${TAG}; no other parameter changed"
 
@@ -69,7 +69,7 @@ RUNNING_IMAGE="$(aws ecs describe-task-definition --task-definition "$TD" --regi
   --query "taskDefinition.containerDefinitions[?name=='${SERVICE_NAME}'].image | [0]" --output text)"
 if [ "$RUNNING_IMAGE" != "$IMAGE_URI" ]; then
   echo "task definition ${TD} has ${RUNNING_IMAGE}, not ${IMAGE_URI}; refusing to roll" >&2
-  exit 1
+  exit 37
 fi
 echo "==> task definition ${TD} carries ${SERVICE_NAME}=${TAG}"
 

data/lib/hecks/projections/deploy/box/templates/deploy-service.taskdef.part

@@ -6,7 +6,7 @@ active_image() {
 }
 CURRENT_IMAGE="$(active_image)"
 case "$CURRENT_IMAGE" in
-  None|"") echo "task definition family ${FAMILY} has no container named ${SERVICE_NAME}" >&2; exit 1 ;;
+  None|"") echo "task definition family ${FAMILY} has no container named ${SERVICE_NAME}" >&2; exit 38 ;;
 esac
 ECR_REPOSITORY="${CURRENT_IMAGE#*/}"
 ECR_REPOSITORY="${ECR_REPOSITORY%%[:@]*}"

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

@@ -8,10 +8,13 @@ URL     ?= @@URL@@
 
 .PHONY: deploy-service smoke-after-deploy check-era
 
-# Pushes one container's already-built local image under a fresh tag and rolls it onto the box.
-# Build the image first; see deploy-service.sh.
+# Pushes one container's already-built local image under a fresh tag and rolls it onto the box, as the
+# service_roll.run command: it runs deploy-service.sh, records the roll in the Hecks database
+# (HECKS_DATABASE, default postgres://hecks@localhost/hecks) and requests the smoke. Build the image
+# first; see deploy-service.sh. EXISTING_TAG=<tag> redeploys a tag already in ECR. Without the
+# database the script runs by itself and the target exits non-zero (24 if it all passed).
 deploy-service:
-	bash ./deploy-service.sh $(SERVICE)
+	@@SERVICE_RECIPE@@
 
 # Waits for the last roll to settle, then dispatches and follows the smoke, as the smoke_run.run
 # command, which runs smoke-after-deploy.sh and records how it ended in the Hecks database

data/lib/hecks/projections/deploy/box/templates/restore-to-rds.sh.tmpl

@@ -9,6 +9,10 @@
 #             direction (swap the hosts and secrets, and SRC_DB and DST_DB)
 #   SRC_DB    the source database (default @@SOURCE_DATABASE@@)
 #   DST_DB    the target database (default @@DATABASE@@)
+#   VERIFY_BY_COMMAND=1   end after the copy and leave the comparison to `hecks deploy data_copy.restore`
+#
+# Ends 60 (a client older than 16), 61 (the target already has a schema), 62 (unexpected restore
+# errors), or, run by hand, verify-copy.sh's 50 (the databases differ).
 #
 # Schemas copied: @@SCHEMAS@@
 #
@@ -34,7 +38,7 @@ if [ "$(pg_major pg_dump || echo 0)" -lt 16 ] && [ -x /opt/homebrew/opt/postgres
   export PATH=/opt/homebrew/opt/postgresql@16/bin:$PATH
 fi
 for t in pg_dump pg_restore psql; do
-  [ "$(pg_major $t || echo 0)" -ge 16 ] || { echo "need $t 16 or newer on the PATH" >&2; exit 1; }
+  [ "$(pg_major $t || echo 0)" -ge 16 ] || { echo "need $t 16 or newer on the PATH" >&2; exit 60; }
 done
 
 WORK=$(mktemp -d)
@@ -66,7 +70,7 @@ echo "source $(SRC 'show server_version'), target $(DST 'show server_version')"
 for S in $SCHEMAS; do
   if [ "$(DST "select count(*) from pg_namespace where nspname='$S'")" != 0 ]; then
     if [ "${FORCE:-}" = 1 ]; then DST "drop schema \"$S\" cascade" >/dev/null; echo "dropped target schema $S"
-    else echo "target already has schema $S; re-run with FORCE=1 to replace it" >&2; exit 1; fi
+    else echo "target already has schema $S; re-run with FORCE=1 to replace it" >&2; exit 61; fi
   fi
 done
 
@@ -77,7 +81,7 @@ for S in $SCHEMAS; do
   TOTAL=$(grep -c 'error:' "$WORK/err_$S.txt" || true)
   UNEXPECTED=$(grep 'error:' "$WORK/err_$S.txt" | grep -vc 'hecks_tr_extract' || true)
   echo "   restore errors: $TOTAL (unexpected: $UNEXPECTED)"
-  if [ "$UNEXPECTED" != 0 ]; then grep 'error:' "$WORK/err_$S.txt" | grep -v 'hecks_tr_extract' | head -5 >&2; exit 1; fi
+  if [ "$UNEXPECTED" != 0 ]; then grep 'error:' "$WORK/err_$S.txt" | grep -v 'hecks_tr_extract' | head -5 >&2; exit 62; fi
 done
 
 # Refresh what pg_restore could not (with the schema on the search_path).
@@ -88,4 +92,5 @@ for S in $SCHEMAS; do
 done
 
 # Same structure, same exact row counts in every table, nothing unpopulated.
+[ -z "${VERIFY_BY_COMMAND:-}" ] || exit 0
 A_DB=$SRC_DB B_DB=$DST_DB bash "$HERE/verify-copy.sh" "$BASTION" "$SRC_HOST" "$SRC_SECRET" "$DST_HOST" "$DST_SECRET"

data/lib/hecks/projections/deploy/box/templates/verify-copy.sh.tmpl

@@ -8,7 +8,7 @@
 #   A_DB, B_DB   the database on each side (default @@DATABASE@@)
 #
 # Schemas compared: @@SCHEMAS@@
-# Exit 0 only if both are identical and no materialized view is unpopulated in either.
+# Exit 0 only if both are identical and no materialized view is unpopulated in either; 50 when they differ.
 set -euo pipefail
 
 BASTION=${1:?bastion instance id}; A_HOST=${2:?}; A_SECRET=${3:?}; B_HOST=${4:?}; B_SECRET=${5:?}
@@ -54,5 +54,5 @@ A "$COUNTS" >"$WORK/counts_a"; B "$COUNTS" >"$WORK/counts_b"
 [ "$(A "$UNPOP")" = 0 ] && [ "$(B "$UNPOP")" = 0 ] || { echo "FAIL: unpopulated materialized views" >&2; BAD=1; }
 diff "$WORK/shape_a" "$WORK/shape_b" >/dev/null || { echo "FAIL: structure differs" >&2; diff "$WORK/shape_a" "$WORK/shape_b" >&2 || true; BAD=1; }
 diff "$WORK/counts_a" "$WORK/counts_b" >/dev/null || { echo "FAIL: row counts differ" >&2; diff "$WORK/counts_a" "$WORK/counts_b" >&2 || true; BAD=1; }
-[ "$BAD" = 0 ] || exit 1
+[ "$BAD" = 0 ] || exit 50
 echo "OK: $(wc -l <"$WORK/counts_a" | tr -d ' ') tables, identical row counts and structure"

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

@@ -2,6 +2,7 @@ require "json"
 require_relative "../../projector"
 require_relative "box/settings"
 require_relative "box/hosting"
+require_relative "box/roll_recipe"
 
 module Hecks
   module Projections
@@ -38,7 +39,9 @@ module Hecks
           '$(HECKS) deploy smoke_run.run project="$(CURDIR)" --wait $(if $(TASKDEF),taskdef=$(TASKDEF)) 2>"$$err"; rc=$$?; \\',
           'if [ $$rc -ne 0 ] && grep -q \'^cannot open Hecks\' "$$err"; then \\',
           '  echo "==> the deploy record was NOT written: $$(grep -m1 \'^cannot open Hecks\' "$$err")" >&2; \\',
-          '  echo "    one-time setup on this machine: createdb hecks, or set HECKS_DATABASE to a Postgres URL" >&2; \\',
+          '  echo "    one-time setup on this machine: a database AND a non-superuser role that owns it" >&2; \\',
+          '  echo "    (a superuser skips the era write-fence, so createdb alone fails), then set" >&2; \\',
+          '  echo "    HECKS_DATABASE=postgres://<role>@localhost/<db>" >&2; \\',
           '  echo "    running the smoke anyway so its result is not lost" >&2; \\',
           '  rm -f "$$err"; TASKDEF="$(TASKDEF)" bash ./smoke-after-deploy.sh; rc=$$?; \\',
           '  echo "==> smoke exit $$rc. The deploy record was NOT written: the database is unavailable (see above)." >&2; \\',
@@ -576,6 +579,8 @@ module Hecks
             # Elastic IP. The default is a production pair, with deletion protection.
             REHEARSAL ?= false
 
+            HECKS ?= hecks
+
             .PHONY: stacks deploy
             stacks:
             \taws cloudformation deploy --template-file rds.yaml --stack-name $(RDS_STACK) --capabilities CAPABILITY_IAM \\
@@ -588,20 +593,9 @@ module Hecks
             \t\tRehearsal=$(REHEARSAL)
 
             deploy:
-            \tbash ./deploy-box.sh $(#{plan.task_definition ? 'TASKDEF' : 'TAGS'})
+            #{RollRecipe.deploy(plan)}
           MAKE
-          "#{base}#{hosting_makefile_tail(plan)}"
-        end
-
-        # With hosting scripts, a deploy ends with the post-deploy smoke and the Makefile includes
-        # the fragment that adds the hosting targets.
-        #
-        # @param plan [Settings::Plan] the resolved settings
-        # @return [String] the Makefile lines that follow the `deploy` recipe, or nothing
-        def hosting_makefile_tail(plan)
-          return "" unless plan.hosting
-
-          "\t$(MAKE) smoke-after-deploy\n\ninclude hosting.mk\n"
+          plan.hosting ? "#{base}\ninclude hosting.mk\n" : base
         end
 
         # Fills `@@NAME@@` markers. A marker alone on its line is replaced together with the line,

data/lib/hecks/projections/site/admin.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "table"
+
+module Hecks
+  module Projections
+    module Site
+      # What a site's route table cannot say about who may use its admin pages: the session cookie,
+      # the host that vouches for it, the roles that count as an admin, and the two routes the
+      # sign-in is built from.
+      #
+      # A project declares one `member` row of a `value_object "Admin"` in the chapter that holds
+      # its route table. `docs/site-routes.md` lists the fields. A project that declares none has
+      # no admin sign-in to project.
+      class Admin
+        Setting = Struct.new(:session_cookie, :session_max_age, :host_env, :host_default, :roles,
+                             :account_path, :members_path, :sso_token_path, :sso_target, :login,
+                             :sso, :verdict_ttl_ms, :timeout_ms, :cms_base, keyword_init: true)
+
+        # The value object a project declares its admin row in.
+        OBJECT = "Admin"
+
+        # The fields the row may carry, with the Ruby class each takes.
+        FIELDS = {
+          session_cookie: String, session_max_age: Integer, host_env: String, host_default: String,
+          roles: String, account_path: String, members_path: String, sso_token_path: String,
+          sso_target: String, login: String, sso: String, verdict_ttl_ms: Integer, timeout_ms: Integer,
+          cms_base: String
+        }.freeze
+
+        # The fields the row must carry.
+        REQUIRED = %i[session_cookie host_env login sso].freeze
+
+        # What a field takes when the row does not carry it.
+        DEFAULTS = {
+          session_max_age: 14 * 24 * 60 * 60, host_default: "http://127.0.0.1:4322",
+          roles: "Admin,Owner", account_path: "/accounts/me", members_path: "/members",
+          sso_token_path: "/accounts/sso-token", sso_target: "/cms/api/sso",
+          verdict_ttl_ms: 10_000, timeout_ms: 5_000, cms_base: "/cms"
+        }.freeze
+
+        # The fields that name a path on the host or the content system, which start with a slash.
+        PATH_FIELDS = %i[account_path members_path sso_token_path sso_target cms_base].freeze
+
+        # @return [Setting] the checked row, defaults filled
+        attr_reader :setting
+
+        # Reads and checks the admin row a chapter declares.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @param table [Table] the checked route table
+        # @return [Admin, nil] the checked setting, or nil when the chapter declares none
+        # @raise [Table::Invalid] when the row is refused or contradicts the routes
+        def self.read(chapter, table:)
+          members = Table.rows_of(chapter, OBJECT)
+          return nil if members.empty?
+
+          new(members, table: table)
+        end
+
+        # @param members [Array<Hash{Symbol => Object}>] the declared rows
+        # @param table [Table] the checked route table
+        # @raise [Table::Invalid] naming every problem when there is one
+        def initialize(members, table:)
+          problems = []
+          problems << "a project declares one Admin row, not #{members.size}" if members.size > 1
+          row = members.first
+          typed = typed_fields(row, problems)
+          @setting = Setting.new(**DEFAULTS, **typed)
+          check(table.rows, problems) if problems.empty?
+          return if problems.empty?
+
+          raise Table::Invalid, "the admin sign-in is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        end
+
+        # @return [Array<String>] the roles that count as an admin
+        def roles = setting.roles.split(",").map(&:strip).reject(&:empty?)
+
+        # @return [String] the path of the content system's sign-in endpoint inside its own API, the
+        #   part of `sso_target` after `<cms_base>/api`
+        def cms_endpoint = setting.sso_target.delete_prefix("#{setting.cms_base}/api")
+
+        private
+
+        def typed_fields(row, problems)
+          unknown = row.keys - FIELDS.keys
+          problems << "Admin row has no field #{unknown.join(', ')}; fields are #{FIELDS.keys.join(', ')}" if unknown.any?
+          (REQUIRED - row.keys).each { |field| problems << "Admin row needs #{field}" }
+          row.slice(*FIELDS.keys).select do |field, value|
+            value.is_a?(FIELDS.fetch(field)) ||
+              (problems << "Admin row has #{field} #{value.inspect}; #{field} is a #{FIELDS.fetch(field)}")
+          end
+        end
+
+        def check(rows, problems)
+          check_paths(problems)
+          check_cms_base(problems)
+          problems << "Admin roles name no role" if roles.empty?
+          check_login(rows, problems)
+          check_sso(rows, problems)
+        end
+
+        def check_paths(problems)
+          (PATH_FIELDS + %i[login sso]).each do |field|
+            value = setting[field]
+            problems << "Admin #{field} #{value.inspect} must start with a slash" unless value.start_with?("/")
+          end
+        end
+
+        # The sign-in endpoint is the content system's own API route, under its base path.
+        def check_cms_base(problems)
+          return if setting.sso_target.start_with?("#{setting.cms_base}/api/")
+
+          problems << "Admin sso_target #{setting.sso_target} must be under #{setting.cms_base}/api/"
+        end
+
+        # The login page is a public row: a visitor with no session must reach it.
+        def check_login(rows, problems)
+          row = rows.find { |candidate| candidate.path == setting.login }
+          if row.nil?
+            problems << "Admin login #{setting.login} is not a route of the table"
+          elsif row.auth != "public"
+            problems << "Admin login #{setting.login} is #{row.auth}; the login page must be public"
+          end
+        end
+
+        # The hand-off to the content system is an admin endpoint: it answers only an admin.
+        def check_sso(rows, problems)
+          row = rows.find { |candidate| candidate.path == setting.sso }
+          if row.nil?
+            problems << "Admin sso #{setting.sso} is not a route of the table"
+          else
+            problems << "Admin sso #{setting.sso} is #{row.auth}; it must be admin" unless row.auth == "admin"
+            problems << "Admin sso #{setting.sso} is a #{row.kind}; it must be an endpoint" unless row.kind == "endpoint"
+          end
+        end
+      end
+    end
+  end
+end