From 487d2b3ba8ecda0251873e613d5409c05d5edf54b7ce374f5c1f823d897d1a6e Mon Sep 17 00:00:00 2001
From: "Marc S. Weidner" <msw@coresecret.dev>
Date: Thu, 11 Jun 2026 17:12:23 +0100
Subject: [PATCH] V9.14.024.2026.06.11

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
---
 lib/lib_build_dir_safety.sh  | 318 +++++++++++++++++++++++++++
 lib/lib_debug_sanitize.sh    | 297 +++++++++++++++++++++++++
 lib/lib_secret_validation.sh | 406 +++++++++++++++++++++++++++++++++++
 3 files changed, 1021 insertions(+)
 create mode 100644 lib/lib_build_dir_safety.sh
 create mode 100644 lib/lib_debug_sanitize.sh
 create mode 100644 lib/lib_secret_validation.sh

diff --git a/lib/lib_build_dir_safety.sh b/lib/lib_build_dir_safety.sh
new file mode 100644
index 0000000..89094df
--- /dev/null
+++ b/lib/lib_build_dir_safety.sh
@@ -0,0 +1,318 @@
+#!/bin/bash
+# SPDX-Version: 3.0
+# SPDX-CreationInfo: 2026-06-11; WEIDNER, Marc S.; <msw@coresecret.dev>
+# SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
+# SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
+# SPDX-FileCopyrightText: 2024-2026; WEIDNER, Marc S.; <msw@coresecret.dev>
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: LicenseRef-CNCL-1.1 OR LicenseRef-CCLA-1.1
+# SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
+# SPDX-PackageName: CISS.debian.live.builder
+# SPDX-Security-Contact: security@coresecret.eu
+# shellcheck disable=SC2154
+
+# Module overview:
+# This module centralizes build-directory safety checks for path validation, builder-ownership markers, and destructive cleanup
+# helpers. It keeps cleanup operations limited to canonical, explicitly validated build-directory paths.
+#
+# Function behavior:
+#   build_dir_safety_error(): writes a scoped build-directory safety error message to stderr.
+#   reject_broad_build_dir_path(): rejects the filesystem root and common top-level system directories as build targets.
+#   validate_build_dir_argument(): validates a non-empty absolute build-directory argument before the path is created.
+#   validate_existing_build_dir(): validates the argument and confirms that it resolves to an existing directory.
+#   require_builder_owned_build_dir(): requires a validated directory with a safe root-owned builder marker.
+#   ensure_builder_owned_build_dir(): creates the marker for a safe empty build directory or verifies an existing marker.
+#   require_builder_owned_subpath(): confirms that a target exists strictly below a verified builder-owned directory.
+#   safe_clean_build_dir_contents(): removes direct build-directory contents while preserving the builder marker.
+#   safe_remove_builder_subpath(): removes one verified subpath below a builder-owned build directory.
+
+guard_sourcing || return "${ERR_GUARD_SRCE}"
+
+#######################################
+# Print a cleanup/path safety error.
+# Globals:
+#   None
+# Arguments:
+#   1: Error detail.
+# Returns:
+#   0: on success
+#######################################
+build_dir_safety_error() {
+  declare detail="${1}"
+
+  printf "\e[91m❌ build directory safety: %s \e[0m\n" "${detail}" >&2
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f build_dir_safety_error
+
+#######################################
+# Reject broad parent directories as build-directory targets.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Canonical path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+reject_broad_build_dir_path() {
+  declare canonical_path="${1}"
+
+  case "${canonical_path}" in
+    "" | "/" | "/bin" | "/boot" | "/dev" | "/etc" | "/home" | "/lib" | "/lib64" | "/opt" | "/proc" | "/root" | "/run" | "/sbin" | "/sys" | "/tmp" | "/usr" | "/var")
+      build_dir_safety_error "refusing broad path."
+      return "${ERR_INVLD_CHAR}"
+      ;;
+    *)
+      ;;
+  esac
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f reject_broad_build_dir_path
+
+#######################################
+# Validate a build-directory argument before it is created.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Build directory path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+validate_build_dir_argument() {
+  declare build_dir="${1}" canonical_path=""
+
+  if [[ -z "${build_dir}" ]]; then
+    build_dir_safety_error "path MUST NOT be empty."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ "${build_dir}" != /* ]]; then
+    build_dir_safety_error "path MUST be absolute."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ -L "${build_dir}" ]]; then
+    build_dir_safety_error "path MUST NOT be a symlink."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  canonical_path="$(realpath -m -- "${build_dir}")"
+  reject_broad_build_dir_path "${canonical_path}" || return "${?}"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_build_dir_argument
+
+#######################################
+# Canonicalize and validate an existing build directory.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Build directory path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+validate_existing_build_dir() {
+  declare build_dir="${1}" canonical_path=""
+
+  validate_build_dir_argument "${build_dir}" || return "${?}"
+
+  if [[ ! -d "${build_dir}" ]]; then
+    build_dir_safety_error "path MUST be an existing directory."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  canonical_path="$(realpath -e -- "${build_dir}")"
+  reject_broad_build_dir_path "${canonical_path}" || return "$?"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_existing_build_dir
+
+#######################################
+# Validate the builder-owned marker in a build directory.
+# Globals:
+#   CISS_BUILD_DIR_MARKER
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Build directory path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+require_builder_owned_build_dir() {
+  declare build_dir="${1}" canonical_path="" marker_path="" marker_owner="" marker_mode="" marker_mode_octal=""
+
+  validate_existing_build_dir "${build_dir}" || return "$?"
+
+  canonical_path="$(realpath -e -- "${build_dir}")"
+  marker_path="${canonical_path}/${CISS_BUILD_DIR_MARKER}"
+
+  if [[ -L "${marker_path}" || ! -f "${marker_path}" ]]; then
+    build_dir_safety_error "builder-owned marker is missing or unsafe."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  marker_owner="$(stat -c '%u:%g' -- "${marker_path}")"
+  if [[ "${marker_owner}" != "0:0" ]]; then
+    build_dir_safety_error "builder-owned marker MUST be owned by root:root."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  marker_mode="$(stat -c '%a' -- "${marker_path}")"
+  marker_mode_octal=$((8#${marker_mode}))
+  if (( (marker_mode_octal & 022) != 0 )); then
+    build_dir_safety_error "builder-owned marker MUST NOT be group- or world-writable."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f require_builder_owned_build_dir
+
+#######################################
+# Create or preserve the builder-owned marker.
+# Globals:
+#   CISS_BUILD_DIR_MARKER
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Build directory path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+ensure_builder_owned_build_dir() {
+  declare build_dir="${1}" canonical_path="" marker_path=""
+
+  validate_existing_build_dir "${build_dir}" || return "${?}"
+
+  canonical_path="$(realpath -e -- "${build_dir}")"
+  marker_path="${canonical_path}/${CISS_BUILD_DIR_MARKER}"
+
+  if [[ -e "${marker_path}" || -L "${marker_path}" ]]; then
+    require_builder_owned_build_dir "${canonical_path}" || return "${?}"
+    return 0
+  fi
+
+  if [[ -d "${canonical_path}/.build" ]]; then
+    build_dir_safety_error "existing live-build state lacks the builder-owned marker."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  install -m 0600 -o root -g root /dev/null "${marker_path}"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f ensure_builder_owned_build_dir
+
+#######################################
+# Validate that a target path is strictly below a builder-owned build directory.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Build directory path.
+#   2: Target-path below the build directory.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+require_builder_owned_subpath() {
+  declare build_dir="${1}" target_path="${2}" build_real="" target_real=""
+
+  require_builder_owned_build_dir "${build_dir}" || return "$?"
+
+  if [[ -z "${target_path}" || -L "${target_path}" || ! -e "${target_path}" ]]; then
+    build_dir_safety_error "target subpath is empty, missing, or a symlink."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  build_real="$(realpath -e -- "${build_dir}")"
+  target_real="$(realpath -e -- "${target_path}")"
+
+  if [[ "${target_real}" == "${build_real}" ]]; then
+    build_dir_safety_error "target subpath MUST NOT be the build directory itself."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  case "${target_real}" in
+    "${build_real}"/*)
+      ;;
+    *)
+      build_dir_safety_error "target subpath MUST stay below the build directory."
+      return "${ERR_INVLD_CHAR}"
+      ;;
+  esac
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f require_builder_owned_subpath
+
+#######################################
+# Remove all contents of the exact builder-owned build directory.
+# Globals:
+#   CISS_BUILD_DIR_MARKER
+# Arguments:
+#   1: Build directory path.
+# Returns:
+#   0: on success
+#   Non-zero: on failure
+#######################################
+safe_clean_build_dir_contents() {
+  declare build_dir="${1}" build_real=""
+
+  require_builder_owned_build_dir "${build_dir}" || return "${?}"
+
+  build_real="$(realpath -e -- "${build_dir}")"
+
+  find "${build_real}" -mindepth 1 -maxdepth 1 -xdev ! -name "${CISS_BUILD_DIR_MARKER}" -exec rm -rf --one-file-system -- {} +
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f safe_clean_build_dir_contents
+
+#######################################
+# Remove one exact builder-owned subpath.
+# Globals:
+#   None
+# Arguments:
+#   1: Build-directory-path.
+#   2: Target-path below build-directory.
+# Returns:
+#   0: on success
+#   Non-zero: on failure
+#######################################
+safe_remove_builder_subpath() {
+  declare build_dir="${1}" target_path="${2}" target_real=""
+
+  require_builder_owned_subpath "${build_dir}" "${target_path}" || return "${?}"
+
+  target_real="$(realpath -e -- "${target_path}")"
+  rm -rf --one-file-system -- "${target_real}"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f safe_remove_builder_subpath
+# vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh
diff --git a/lib/lib_debug_sanitize.sh b/lib/lib_debug_sanitize.sh
new file mode 100644
index 0000000..394df98
--- /dev/null
+++ b/lib/lib_debug_sanitize.sh
@@ -0,0 +1,297 @@
+#!/bin/bash
+# SPDX-Version: 3.0
+# SPDX-CreationInfo: 2026-06-11; WEIDNER, Marc S.; <msw@coresecret.dev>
+# SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
+# SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
+# SPDX-FileCopyrightText: 2024-2026; WEIDNER, Marc S.; <msw@coresecret.dev>
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: LicenseRef-CNCL-1.1 OR LicenseRef-CCLA-1.1
+# SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
+# SPDX-PackageName: CISS.debian.live.builder
+# SPDX-Security-Contact: security@coresecret.eu
+# shellcheck disable=SC2154
+
+# Function behavior:
+#   debug_sanitize_escape_glob(): Escape Bash glob metacharacters so exact values can be used safely in parameter-substitution matches.
+#   debug_sanitize_read_file(): Read a text file into a named variable while preserving trailing newline bytes.
+#   debug_sanitize_add_secret(): Add one non-empty exact secret value to the in-memory redaction list, avoiding duplicates.
+#   debug_sanitize_add_secret_file(): Add the exact content of a regular, non-symlink secret file to the redaction list.
+#   debug_sanitize_collect_secrets(): Add controlled secret variables and secret-file contents to the redaction list.
+#   collect_debug_secret_values(): Collect exact secret values while xtrace is temporarily disabled.
+#   finalize_debug_xtrace_logging(): Permanently disable xtrace and close the xtrace log FD before rewriting logs.
+#   debug_sanitize_log_file(): Redact collected exact secret values from one log file and restrict its permissions.
+#   sanitize_debug_logs(): Run the final exact-value sanitization pass across closed debug, variable, and error logs.
+
+guard_sourcing || return "${ERR_GUARD_SRCE}"
+
+declare -ga _ARY_DEBUG_SECRET_VALUES=()
+declare -g  _VAR_DEBUG_XTRACE_FINALIZED="false"
+
+#######################################
+# Escape Bash glob metacharacters for exact parameter-substitution matching.
+# Globals:
+#   None
+# Arguments:
+#   1: Raw value.
+# Returns:
+#   0: on success
+#######################################
+debug_sanitize_escape_glob() {
+  declare value="${1}"
+
+  value="${value//\\/\\\\}"
+  value="${value//\*/\\*}"
+  value="${value//\?/\\?}"
+  value="${value//\[/\\[}"
+  value="${value//\]/\\]}"
+
+  printf '%s' "${value}"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f debug_sanitize_escape_glob
+
+#######################################
+# Read a text file into a variable, preserving trailing newlines.
+# Globals:
+#   None
+# Arguments:
+#   1: File path.
+#   2: Output variable name.
+# Returns:
+#   0: on success
+#######################################
+debug_sanitize_read_file() {
+  declare file_path="${1}" output_var="${2}" content=""
+
+  IFS= read -r -d '' content < "${file_path}" || true
+  printf -v "${output_var}" '%s' "${content}"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f debug_sanitize_read_file
+
+#######################################
+# Add one exact secret value to the redaction list.
+# Globals:
+#   _ARY_DEBUG_SECRET_VALUES
+# Arguments:
+#   1: Secret value.
+# Returns:
+#   0: on success
+#######################################
+debug_sanitize_add_secret() {
+  declare secret_value="${1}" known_value=""
+
+  [[ -n "${secret_value}" ]] || return 0
+
+  for known_value in "${_ARY_DEBUG_SECRET_VALUES[@]:-}"; do
+    [[ "${known_value}" == "${secret_value}" ]] && return 0
+  done
+
+  _ARY_DEBUG_SECRET_VALUES+=("${secret_value}")
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f debug_sanitize_add_secret
+
+#######################################
+# Add a secret file's exact content to the redaction list.
+# Globals:
+#   _ARY_DEBUG_SECRET_VALUES
+# Arguments:
+#   1: File path.
+# Returns:
+#   0: on success
+#######################################
+debug_sanitize_add_secret_file() {
+  declare file_path="${1}" secret_value=""
+
+  [[ -n "${file_path}" && -f "${file_path}" && ! -L "${file_path}" ]] || return 0
+  [[ -s "${file_path}" ]] || return 0
+
+  debug_sanitize_read_file "${file_path}" secret_value
+  debug_sanitize_add_secret "${secret_value}"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f debug_sanitize_add_secret_file
+
+#######################################
+# Gather exact values from controlled secret variables and files.
+# Globals:
+#   _ARY_DEBUG_SECRET_VALUES
+#   VAR_HASHED_PWD
+#   VAR_SIGNING_KEY_PASSFILE
+#   VAR_TMP_SECRET
+# Arguments:
+#   None
+# Returns:
+#   0: on success
+#######################################
+debug_sanitize_collect_secrets() {
+  declare secret_file=""
+
+  if [[ -n "${VAR_HASHED_PWD:-}" ]]; then
+    debug_sanitize_add_secret "${VAR_HASHED_PWD}"
+  fi
+
+  if [[ -n "${VAR_SIGNING_KEY_PASSFILE:-}" ]]; then
+    debug_sanitize_add_secret_file "${VAR_SIGNING_KEY_PASSFILE}"
+  fi
+
+  if [[ -n "${VAR_TMP_SECRET:-}" && -d "${VAR_TMP_SECRET}" && ! -L "${VAR_TMP_SECRET}" ]]; then
+    while IFS= read -r -d '' secret_file; do
+      debug_sanitize_add_secret_file "${secret_file}"
+    done < <(find "${VAR_TMP_SECRET}" -xdev -type f -print0 2>/dev/null || true)
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f debug_sanitize_collect_secrets
+
+#######################################
+# Collect exact secret values without tracing secret-bearing operations.
+# Globals:
+#   _VAR_DEBUG_XTRACE_FINALIZED
+# Arguments:
+#   None
+# Returns:
+#   0: on success
+#######################################
+collect_debug_secret_values() {
+  declare tracing_was_enabled="false"
+
+  case "$-" in
+    *x*)
+      tracing_was_enabled="true"
+      set +x
+      ;;
+    *)
+      ;;
+  esac
+
+  debug_sanitize_collect_secrets || true
+
+  if [[ "${tracing_was_enabled}" == "true" && "${_VAR_DEBUG_XTRACE_FINALIZED}" != "true" ]]; then
+    set -x
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f collect_debug_secret_values
+
+#######################################
+# Permanently stop xtrace logging before the final log rewrite.
+# Globals:
+#   BASH_XTRACEFD
+#   _VAR_DEBUG_XTRACE_FINALIZED
+# Arguments:
+#   None
+# Returns:
+#   0: on success
+#######################################
+finalize_debug_xtrace_logging() {
+  declare xtrace_fd=""
+
+  set +x
+
+  if [[ "${BASH_XTRACEFD:-}" =~ ^[0-9]+$ ]]; then
+    xtrace_fd="${BASH_XTRACEFD}"
+    unset BASH_XTRACEFD
+
+    if (( xtrace_fd > 2 )); then
+      exec {xtrace_fd}>&- 2>/dev/null || true
+    fi
+  fi
+
+  _VAR_DEBUG_XTRACE_FINALIZED="true"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f finalize_debug_xtrace_logging
+
+#######################################
+# Redact exact secret values from one log file.
+# Globals:
+#   _ARY_DEBUG_SECRET_VALUES
+# Arguments:
+#   1: Log file path.
+# Returns:
+#   0: on success
+#######################################
+debug_sanitize_log_file() {
+  declare log_file="${1}" log_content="" secret_value="" secret_pattern="" redaction=""
+  declare -i secret_len=0
+
+  [[ -n "${log_file}" && -f "${log_file}" && ! -L "${log_file}" ]] || return 0
+
+  debug_sanitize_read_file "${log_file}" log_content
+
+  for secret_value in "${_ARY_DEBUG_SECRET_VALUES[@]:-}"; do
+
+    [[ -n "${secret_value}" ]] || continue
+
+    secret_pattern="$(debug_sanitize_escape_glob "${secret_value}")"
+    secret_len="${#secret_value}"
+    printf -v redaction '%*s' "${secret_len}" ''
+    redaction="${redaction// /*}"
+    log_content="${log_content//${secret_pattern}/${redaction}}"
+
+  done
+
+  printf '%s' "${log_content}" >| "${log_file}"
+  chmod 0600 "${log_file}" 2>/dev/null || true
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f debug_sanitize_log_file
+
+#######################################
+# Final exact-value debug log sanitization pass.
+# Globals:
+#   LOG_DEBUG
+#   LOG_ERROR
+#   LOG_VAR
+# Arguments:
+#   None
+# Returns:
+#   0: on success
+#######################################
+sanitize_debug_logs() {
+  declare old_lc_all="${LC_ALL:-}" log_file=""
+
+  finalize_debug_xtrace_logging || true
+
+  LC_ALL=C
+
+  debug_sanitize_collect_secrets || true
+
+  for log_file in "${LOG_DEBUG:-}" "${LOG_VAR:-}" "${LOG_ERROR:-}"; do
+    debug_sanitize_log_file "${log_file}" || true
+  done
+
+  LC_ALL="${old_lc_all}"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f sanitize_debug_logs
+# vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh
diff --git a/lib/lib_secret_validation.sh b/lib/lib_secret_validation.sh
new file mode 100644
index 0000000..4d78485
--- /dev/null
+++ b/lib/lib_secret_validation.sh
@@ -0,0 +1,406 @@
+#!/bin/bash
+# SPDX-Version: 3.0
+# SPDX-CreationInfo: 2026-06-11; WEIDNER, Marc S.; <msw@coresecret.dev>
+# SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.live.builder.git
+# SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
+# SPDX-FileCopyrightText: 2024-2026; WEIDNER, Marc S.; <msw@coresecret.dev>
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: LicenseRef-CNCL-1.1 OR LicenseRef-CCLA-1.1
+# SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
+# SPDX-PackageName: CISS.debian.live.builder
+# SPDX-Security-Contact: security@coresecret.eu
+# shellcheck disable=SC2154
+
+guard_sourcing || return "${ERR_GUARD_SRCE}"
+
+#######################################
+# Print a validation error without echoing secret values.
+# Globals:
+#   None
+# Arguments:
+#   1: Validation label.
+#   2: Error detail.
+# Returns:
+#   0: on success
+#######################################
+secret_validation_error() {
+  declare label="$1" detail="$2"
+
+  printf "\e[91mERROR: %s: %s\e[0m\n" "${label}" "${detail}" >&2
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f secret_validation_error
+
+#######################################
+# Validate a filename-only secret argument.
+# Globals:
+#   ERR_ARG_MSMTCH
+# Arguments:
+#   1: Validation label.
+#   2: Filename.
+# Returns:
+#   0: on success
+#   ERR_ARG_MSMTCH: on failure
+#######################################
+validate_secret_filename() {
+  declare label="$1" filename="$2"
+  declare filename_regex='^[A-Za-z0-9._@%+=:,~-]+$'
+
+  if [[ -z "${filename}" ]]; then
+    secret_validation_error "${label}" "filename MUST NOT be empty."
+    return "${ERR_ARG_MSMTCH}"
+  fi
+
+  if [[ "${filename}" == "." || "${filename}" == ".." ]]; then
+    secret_validation_error "${label}" "filename MUST NOT be '.' or '..'."
+    return "${ERR_ARG_MSMTCH}"
+  fi
+
+  if [[ "${filename}" == -* ]]; then
+    secret_validation_error "${label}" "filename MUST NOT start with '-'."
+    return "${ERR_ARG_MSMTCH}"
+  fi
+
+  if [[ "${filename}" == */* || "${filename}" == *\\* ]]; then
+    secret_validation_error "${label}" "filename MUST NOT contain path separators."
+    return "${ERR_ARG_MSMTCH}"
+  fi
+
+  if [[ ! "${filename}" =~ ${filename_regex} ]]; then
+    secret_validation_error "${label}" "filename contains unsupported characters."
+    return "${ERR_ARG_MSMTCH}"
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_secret_filename
+
+#######################################
+# Validate the fixed tmpfs secret root.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Secret root path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+validate_secret_root() {
+  declare secret_root="$1" root_owner="" root_mode="" root_mode_octal="" root_fs=""
+
+  if [[ -z "${secret_root}" ]]; then
+    secret_validation_error "secret root" "path MUST NOT be empty."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ -L "${secret_root}" ]]; then
+    secret_validation_error "secret root" "path MUST NOT be a symlink."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ ! -d "${secret_root}" ]]; then
+    secret_validation_error "secret root" "path MUST be an existing directory."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  root_owner="$(stat -c '%u:%g' -- "${secret_root}")"
+  if [[ "${root_owner}" != "0:0" ]]; then
+    secret_validation_error "secret root" "directory MUST be owned by root:root."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  root_mode="$(stat -c '%a' -- "${secret_root}")"
+  root_mode_octal=$((8#${root_mode}))
+  if (( (root_mode_octal & 077) != 0 || (root_mode_octal & 0700) != 0700 )); then
+    secret_validation_error "secret root" "directory mode MUST be 0700 or stricter."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  root_fs="$(stat -f -c '%T' -- "${secret_root}")"
+  if [[ "${root_fs}" != "tmpfs" && "${root_fs}" != "ramfs" ]]; then
+    secret_validation_error "secret root" "directory MUST be backed by tmpfs or ramfs."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  # shellcheck disable=SC2312
+  if find "${secret_root}" -xdev -type l -print -quit | grep -q .; then
+    secret_validation_error "secret root" "secret tree MUST NOT contain symlinks."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  # shellcheck disable=SC2312
+  if find "${secret_root}" -xdev \( -type b -o -type c -o -type p -o -type s \) -print -quit | grep -q .; then
+    secret_validation_error "secret root" "secret tree MUST NOT contain special files."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_secret_root
+
+#######################################
+# Normalize ownership and mode of regular files in the secret root.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Secret root path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+harden_secret_root_files() {
+  declare secret_root="$1"
+
+  validate_secret_root "${secret_root}" || return "$?"
+
+  find "${secret_root}" -xdev -type f -exec chown root:root -- {} +
+  find "${secret_root}" -xdev -type f -exec chmod 0400 -- {} +
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f harden_secret_root_files
+
+#######################################
+# Validate that an existing absolute path is a regular non-symlink file.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Validation label.
+#   2: File path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+validate_secret_absolute_file_basics() {
+  declare label="$1" file_path="$2"
+
+  if [[ -z "${file_path}" ]]; then
+    secret_validation_error "${label}" "file path MUST NOT be empty."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ "${file_path}" != /* ]]; then
+    secret_validation_error "${label}" "file path MUST be absolute."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ -L "${file_path}" ]]; then
+    secret_validation_error "${label}" "file MUST NOT be a symlink."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ ! -f "${file_path}" ]]; then
+    secret_validation_error "${label}" "file MUST be an existing regular file."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_secret_absolute_file_basics
+
+#######################################
+# Validate a strict secret file.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Validation label.
+#   2: File path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+validate_secret_file_path() {
+  declare label="$1" file_path="$2" file_owner="" file_mode="" file_mode_octal=""
+
+  validate_secret_absolute_file_basics "${label}" "${file_path}" || return "$?"
+
+  file_owner="$(stat -c '%u:%g' -- "${file_path}")"
+  if [[ "${file_owner}" != "0:0" ]]; then
+    secret_validation_error "${label}" "file MUST be owned by root:root."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  file_mode="$(stat -c '%a' -- "${file_path}")"
+  file_mode_octal=$((8#${file_mode}))
+  if (( (file_mode_octal & 077) != 0 || (file_mode_octal & 0400) != 0400 )); then
+    secret_validation_error "${label}" "file mode MUST allow root read and no group/other access."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_secret_file_path
+
+#######################################
+# Validate a filename-only secret stored below the fixed secret root.
+# Globals:
+#   VAR_TMP_SECRET
+# Arguments:
+#   1: Validation label.
+#   2: Filename.
+# Returns:
+#   0: on success
+#   Non-zero: on failure
+#######################################
+validate_secret_file_in_root() {
+  declare label="$1" filename="$2"
+
+  validate_secret_filename "${label}" "${filename}" || return "$?"
+  validate_secret_file_path "${label}" "${VAR_TMP_SECRET}/${filename}" || return "$?"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_secret_file_in_root
+
+#######################################
+# Validate a public input file copied into the ISO.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Validation label.
+#   2: File path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+validate_public_input_file() {
+  declare label="$1" file_path="$2" file_owner="" file_mode="" file_mode_octal=""
+
+  validate_secret_absolute_file_basics "${label}" "${file_path}" || return "$?"
+
+  file_owner="$(stat -c '%u:%g' -- "${file_path}")"
+  if [[ "${file_owner}" != "0:0" ]]; then
+    secret_validation_error "${label}" "file MUST be owned by root:root."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  file_mode="$(stat -c '%a' -- "${file_path}")"
+  file_mode_octal=$((8#${file_mode}))
+  if (( (file_mode_octal & 022) != 0 )); then
+    secret_validation_error "${label}" "file MUST NOT be group- or world-writable."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_public_input_file
+
+#######################################
+# Validate the authorized_keys directory.
+# Globals:
+#   ERR_INVLD_CHAR
+# Arguments:
+#   1: Directory path.
+# Returns:
+#   0: on success
+#   ERR_INVLD_CHAR: on failure
+#######################################
+validate_ssh_pubkey_directory() {
+  declare key_dir="$1" key_file="" dir_owner="" dir_mode="" dir_mode_octal=""
+
+  if [[ -z "${key_dir}" ]]; then
+    secret_validation_error "--ssh-pubkey" "directory path MUST NOT be empty."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ "${key_dir}" != /* ]]; then
+    secret_validation_error "--ssh-pubkey" "directory path MUST be absolute."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ -L "${key_dir}" ]]; then
+    secret_validation_error "--ssh-pubkey" "directory MUST NOT be a symlink."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  if [[ ! -d "${key_dir}" ]]; then
+    secret_validation_error "--ssh-pubkey" "directory MUST exist."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  dir_owner="$(stat -c '%u:%g' -- "${key_dir}")"
+  if [[ "${dir_owner}" != "0:0" ]]; then
+    secret_validation_error "--ssh-pubkey" "directory MUST be owned by root:root."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  dir_mode="$(stat -c '%a' -- "${key_dir}")"
+  dir_mode_octal=$((8#${dir_mode}))
+  if (( (dir_mode_octal & 022) != 0 )); then
+    secret_validation_error "--ssh-pubkey" "directory MUST NOT be group- or world-writable."
+    return "${ERR_INVLD_CHAR}"
+  fi
+
+  key_file="${key_dir}/authorized_keys"
+  validate_public_input_file "--ssh-pubkey authorized_keys" "${key_file}" || return "$?"
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_ssh_pubkey_directory
+
+#######################################
+# Validate all selected secret inputs after argument parsing.
+# Globals:
+#   VAR_AGE
+#   VAR_AGE_KEY
+#   VAR_LUKS
+#   VAR_LUKS_KEY
+#   VAR_SIGNER
+#   VAR_SIGNING_CA
+#   VAR_SIGNING_KEY
+#   VAR_SIGNING_KEY_PASS
+#   VAR_SSHPUBKEY
+#   VAR_TMP_SECRET
+# Arguments:
+#   None
+# Returns:
+#   0: on success
+#   Non-zero: on failure
+#######################################
+validate_selected_secret_inputs() {
+  if [[ "${VAR_AGE,,}" == "true" ]]; then
+    validate_secret_file_in_root "--key_age" "${VAR_AGE_KEY}" || return "$?"
+  fi
+
+  if [[ "${VAR_LUKS,,}" == "true" ]]; then
+    validate_secret_file_in_root "--key_luks" "${VAR_LUKS_KEY}" || return "$?"
+  fi
+
+  if [[ "${VAR_SIGNER,,}" == "true" ]]; then
+    validate_secret_file_in_root "--signing_key" "${VAR_SIGNING_KEY}" || return "$?"
+    validate_secret_file_in_root "--signing_key_pass" "${VAR_SIGNING_KEY_PASS}" || return "$?"
+  fi
+
+  if [[ -n "${VAR_SIGNING_CA:-}" ]]; then
+    validate_secret_file_in_root "--signing_ca" "${VAR_SIGNING_CA}" || return "$?"
+  fi
+
+  if [[ -n "${VAR_SSHPUBKEY:-}" ]]; then
+    validate_ssh_pubkey_directory "${VAR_SSHPUBKEY}" || return "$?"
+  fi
+
+  return 0
+}
+### Prevents accidental 'unset -f'.
+# shellcheck disable=SC2034
+readonly -f validate_selected_secret_inputs
+# vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh