V9.14.000.2026.06.07

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>

docs/CODING_CONVENTION.md

@@ -7,84 +7,200 @@ include_toc: true
 
 **Centurion Intelligence Consulting Agency Information Security Standard**<br>
 *The CISS Debian Installer provides a fully automated and hardened installation process.*<br>
-**Master Version**: 8.00<br>
-**Build**: V8.00.000.2025.06.17<br>
+**Master Version**: 9.00<br>
+**Build**: V9.14.000.2026.06.07<br>
 
-# 2. Coding Style
+# 2. Purpose
 
-## 2.1. PR
+This document defines detailed coding conventions for CISS.debian.installer. `AGENTS.md` is the short operational guide for
+Codex. `code_review.md` is used for review tasks and final self-review.
 
-You'd make the life of the maintainers easier if you submit only _one_ patch with _one_ functional change per PR.
+The repository implements a Bash-first Debian installer for hardened, reproducible system installation workflows. Treat every
+change as security-sensitive, disk-destruction-sensitive, and boot-chain-sensitive, especially changes affecting partitioning,
+LUKS, Btrfs, initramfs, Dropbear remote unlock, GRUB, package sources, signatures, checksums, hardening settings, or logs.
 
-## 2.2 Documentation
+# 3. Change discipline
 
-Some people really read that ! New features would need to be documented in the appropriate section in `usage()` and in
-`~/docs/DOCUMENTATION.md`.
+- Keep changes small, local, and reviewable.
+- Make one functional change per patch set.
+- Preserve existing architecture, naming style, error handling, formatting, and security posture.
+- Target Debian 13 Trixie unless the task or repository explicitly states otherwise.
+- Do not introduce Ubuntu-specific assumptions.
+- Do not invent Debian Installer, debootstrap, initramfs-tools, cryptsetup, GRUB, systemd, Btrfs, Debian package, or upstream
+  tool behavior.
+- Verify uncertain behavior against repository code or authoritative upstream documentation.
+- Do not weaken cryptography, authentication, sandboxing, permission checks, TLS verification, signature verification,
+  checksum verification, provenance verification, or input validation unless explicitly requested and documented.
+- Do not perform unrelated cleanup or formatting churn.
 
-## 2.3. Coding
+# 4. Installer phase awareness
 
-### 2.3.1. Shell / bash
+Identify the affected phase before changing behavior:
 
-Bash is actually quite powerful—not only with respect to sockets. It's not as mighty as perl or python, but there are a lot of
-neat features. Here's how you make use of them. Besides those short hints here, there's a wealth of information there.
+- `ciss_debian_installer.sh`: host-side entrypoint, root/Bash checks, lock handling, trap activation, and phase order.
+- `meta_loader_*.sh`: ordered sourcing of variables, functions, and libraries via `source_guard`.
+- `.preseed/preseed.yaml`, `.preseed/partitioning.yaml`, `.preseed/SECRETS.yaml`: installer settings, partition recipes, and
+  secret material.
+- `lib/cdi_0100_arg/*`: CLI argument sanitation, parsing, priority handling, and passphrase-module argument support.
+- `func/cdi_1200_validation/*` and `func/cdi_1250_yaml/*`: element, IP, preseed, YAML, and secret validation.
+- `func/cdi_3200_partitioning/*`: destructive disk wiping, partition creation, LUKS setup, formatting, mount ordering, and UUID
+  logging.
+- `func/cdi_4000_debootstrap/*`: debootstrap, target mount preparation, base target setup, hostname, resolver, timezone, and
+  locale setup.
+- `func/cdi_4100_base/*`: APT source generation, updates, kernel/initramfs installation, toolset, systemd, machine-id,
+  firmware, microcode, Chrony, and base packages.
+- `func/cdi_4200_boot/*`: fstab, crypttab, cryptsetup-initramfs, GRUB installation, GRUB password, and boot parameters.
+- `func/cdi_4300_network/*`: target networking, network security, Dropbear build/initramfs/setup, initramfs update, and SSH.
+- `func/cdi_4400_hardening/*`: kernel modules, sysctl, fail2ban, filesystem permissions, entropy, memory, OpenSSL, UFW, USB,
+  and malware-auditing hardening.
+- `func/cdi_4500_user/*`: account preparation, password policy, user setup, SSH keys, privileges, and timing fields.
+- `func/cdi_4600_packages/*`: package installation, security profile installation, verification, and auditing packages.
+- `func/cdi_4900_xtended/*`: final commands, logrotate setup, and target chroot exit.
+- `func/cdi_5000_recovery/*`: recovery target debootstrap and finalization when recovery is enabled.
+- `includes/target/*`: files installed into the target system, including initramfs-tools hooks/scripts/files and service
+  configuration.
+- `includes/chroot/hooks/*`: chroot hook payloads.
+- `upgrades/*`: vendored upgrade/build material for Dropbear, Linux image options, and Secure Boot work.
+- `py/*`: Python configurator support.
 
-* Don't use backticks anymore, use `$(..)` instead
-* Use double square `[[]]` brackets (_conditional expressions)_ instead of single square `[]` brackets
-* In double square brackets, avoid quoting at the right-hand side if not necessary. For regex matching (`=~`) you shouldn't
-  quote at all.
-* The [BashPitfalls](http://mywiki.wooledge.org/BashPitfalls) is a good read!
-* Whenever possible try to avoid `tr` `sed` `awk` and use bash internal functions instead, see
-  e.g., [bash shell parameter substitution](http://www.cyberciti.biz/tips/bash-shell-parameter-substitution-2.html). It is
-  slower as it forks, fopens and pipes back the result.
-* `read` often can replace `awk`: `IFS=, read -ra a b c <<< "$line_with_comma"`
-* Bash can also deal perfectly with regular expressions, see
-  e.g., [here](https://www.networkworld.com/article/2693361/unix-tip-using-bash-s-regular-expressions.html)
-  and [here](https://unix.stackexchange.com/questions/421460/bash-regex-and-https-regex101-com).
-* If you still need to use any of `tr`, `sed` and `awk`: try to avoid a mix of several external binaries e.g., if you can
-  achieve the same with e.g. `awk`.
-* Be careful with very advanced bash features. Mac OS X is still using bash version 3 ([differences](http://tldp.org/LDP/abs/html/bashver4.html)).
-* Always use a return value for a function/method. 0 means all is fine.
-* Make use of [shellcheck](https://github.com/koalaman/shellcheck) if possible.
-* Follow the [shellformat](https://google.github.io/styleguide/shellguide.html) Shell-Style Guide.
+Keep host-side behavior, target chroot behavior, initramfs behavior, and bootloader behavior separate.
 
-### 2.3.2. Shell specific
+# 5. Bash baseline
 
-* Security:
-  * Watch out for any input especially (but not only) supplied from the server. Input should never be trusted.
-  * Unless you're really sure where the values come from, variables need to be put in quotes.
+- Use Bash for installer logic and orchestration.
+- Use POSIX shell only where an existing Debian interface file requires it, such as an initramfs hook or script that already
+  declares `#!/bin/sh`.
+- The main installer requires Bash 5.1 or newer; do not add compatibility code for older Bash versions unless explicitly
+  requested.
+- Prefer `set -Ceuo pipefail` for executable Bash scripts where feasible. In sourced modules, preserve the caller's shell
+  option and trap model unless the surrounding code already changes it intentionally.
+- Preserve `guard_sourcing || return "${ERR_GUARD_SOURCE}"` in sourced modules that use it.
+- Preserve `source_guard`-based module loading.
+- Preserve `readonly -f` on functions where surrounding files use it.
+- Do not overwrite existing `ERR`, `EXIT`, `INT`, or `TERM` traps. Coordinate any trap change with `lib/cdi_0060_traps/*` and
+  initramfs runtime scripts.
 
-### 2.3.3. Variables
+# 6. Bash style
 
-* Use **"speaking variables"** but don't overdo it with the length.
-* No _camelCase_, please. We distinguish between lowercase and uppercase only.
-  * Global variables:
-    * use them only when really necessary,
-    * in CAPS,
-    * initialize them (`declare -g VAR_EXAMPLE=""`),
-    * SHOULD start with:
-      * `ARY_`  for Arrays,
-      * `C_`    for Variables defining colored outputs,
-      * `ERR_`  for Error Codes Variables,
-      * `HMP_`  for HashMap Arrays,
-      * `LOG_`  for Logfile Variables,
-      * `PID_`  for PID Variables,
-      * `PIPE_` for PIPE Variables,
-      * `VAR_`  for Variables
-  * Local variables:
-    * are lower case,
-    * declare them before usage (`declare` eq `local`),
-    * initialize them (`declare var_example=""`),
-    * SHOULD start with:
-      * `ary_` for Arrays,
-      * `c_` for Variables defining colored outputs,
-      * `err_` for Error Codes Variables,
-      * `hmp_` for HashMap Arrays,
-      * `log_` for Logfile Variables,
-      * `var_` for Variables.
+- Quote expansions unless word splitting or globbing is explicitly required.
+- Prefer arrays for commands and options.
+- Use `[[ ... ]]` for Bash conditionals.
+- Use `case` for option dispatch and multi-branch string handling.
+- Use `$(...)` command substitution, not backticks.
+- Do not use `eval`.
+- Avoid parsing `ls`.
+- Prefer `command -v` over `which`.
+- Check command results explicitly when failure needs custom logging or cleanup.
+- Keep functions small enough to review.
+- End functions explicitly with `return 0` where consistent with surrounding code.
+- Use English comments. Comment non-obvious security, disk, cryptographic, initramfs, or boot-chain decisions.
 
-# 3. Misc
+# 7. Variables and naming
 
-* Test before doing a PR! Best if you check with two bad and two good examples, which should then work as expected.
+Follow the existing repository naming style:
+
+- Global variables are uppercased and initialized before use.
+- Global arrays and maps use established prefixes such as `ARY_`, `HMP_`, `C_`, `ERR_`, `LOG_`, `PID_`, `PIPE_`, and `VAR_`.
+- Local variables are lowercase and initialized before use.
+- Local arrays and helper variables use established prefixes such as `ary_`, `hmp_`, `c_`, `err_`, `log_`, and `var_`.
+- Use `declare` consistently with surrounding files.
+- Function names use lowercase words separated by underscores.
+- Avoid new global variables when an argument, local variable, or existing helper is sufficient.
+- Keep Boolean-like values normalized where existing code expects lowercase strings.
+
+# 8. Input validation, secrets, and files
+
+- Treat CLI arguments, YAML values, environment variables, generated paths, network data, package metadata, and user-provided
+  files as untrusted until validated.
+- Validate disk names, partition numbers, mount paths, filesystem names, Debian suites, architecture names, ports, IP
+  addresses, package names, URLs, feature flags, and file paths before use.
+- Fail closed when validation cannot prove that continuing is safe.
+- Do not print secrets, passphrases, private keys, tokens, decrypted SOPS values, or sensitive environment values.
+- Keep debug tracing disabled around secret handling unless the local guard explicitly protects sensitive values.
+- Use restrictive permissions for generated key material, passphrase files, LUKS header backups, SSH material, and root-only
+  configuration.
+- Prefer `mktemp` for temporary files and clean them up with existing cleanup or trap helpers.
+- Preserve existing secure deletion helpers where used for passphrase or key material.
+- Do not add a persistent state unless the behavior is intentional, scoped, and documented.
+
+# 9. Disk, partitioning, and cryptsetup safety
+
+- Treat changes under `func/cdi_3200_partitioning/*` as destructive by default.
+- Never run partitioning, formatting, LUKS, `blkdiscard`, `sgdisk --zap-all`, or `dd` validation on a real device unless the
+  task explicitly requests it, and the target is safely isolated.
+- Preserve explicit device scoping from `.preseed/partitioning.yaml`.
+- Preserve udev settling and UUID/PARTUUID collection where disk identity is needed by later phases.
+- Preserve LUKS2 defaults and stronger cryptographic settings unless the task explicitly changes them.
+- Do not weaken PBKDF, cipher, hash, key size, integrity, discard, or keyslot behavior without documenting the risk.
+- Preserve the special handling for encrypted `/boot`, root, recovery, ephemeral `SWAP`, and ephemeral `/tmp`.
+- Keep LUKS header backups encrypted when backup behavior is enabled and remove plaintext backup material after encryption.
+- Keep `/etc/fstab` and `/etc/crypttab` generation consistent with mapper names, UUIDs, PARTUUIDs, filesystem types, and mount
+  options.
+- Preserve Btrfs subvolume and snapshot semantics when changing Btrfs mount or formatting logic.
+
+# 10. Chroot, target, and boot-chain safety
+
+- Use `chroot_exec` for simple command execution in the target.
+- Use `chroot_script` or `chroot_stdin` for shell constructs, redirection, pipelines, loops, or larger payloads.
+- Preserve the sanitized `env -i` target environment unless a task explicitly requires a new variable.
+- Do not leak host paths or host environment assumptions into the target system.
+- Preserve target mount setup and teardown behavior.
+- Keep initramfs-tools hooks and scripts in their expected directories; do not add ad-hoc phase arguments.
+- Preserve Dropbear initramfs forced-command, unlock-wrapper integrity checks, signature verification, and nuke behavior.
+- Preserve GRUB support for encrypted boot paths, and the repository's UEFI/BIOS handling unless explicitly changed.
+- Do not change UEFI NVRAM behavior or fallback boot paths without documenting the boot-chain impact.
+
+# 11. Dependencies and downloads
+
+- Do not add new runtime dependencies unless the task requires them.
+- Prefer standard Debian tooling or existing project helpers.
+- When a dependency is needed, document why the existing toolchain, or a standard alternative is insufficient.
+- Do not add remote downloads, auto-update behavior, telemetry, or network callbacks without explicit justification.
+- For required downloads, use HTTPS where applicable and preserve or add signature, checksum, or provenance verification.
+- Do not use `curl | sh`, `wget | sh`, or equivalent execution of unaudited remote content.
+- Preserve package authentication and APT source integrity checks.
+
+# 12. Documentation rules
+
+- Update documentation together with behavior changes.
+- New or changed CLI options must update `usage()` and relevant documentation.
+- New or changed YAML/preseed keys must update the relevant `.preseed` example or project documentation.
+- Boot parameter changes must update `docs/man/BOOTPARAMS.md` when applicable.
+- Security-sensitive behavior changes must update the relevant manual, audit, or security documentation when applicable.
+- Generated examples must stay valid for Debian 13 Trixie unless the task explicitly targets another release.
+- Code comments, embedded prompts, commit messages, and repository documentation should normally be written in English.
+
+# 13. Formatting
+
+- Preserve SPDX headers and existing file headers where present.
+- New source or configuration files should include the project SPDX header when comparable files already use one.
+- Follow `.editorconfig`: LF line endings, UTF-8, two-space indentation for most repository files, four-space indentation for
+  Python, and readable line lengths.
+- Preserve the local Vim modeline style in source/config files where neighboring files use it.
+- Keep Markdown concise and structured. Avoid decorative text that does not define repository behavior.
+- Do not churn formatting unrelated to the task.
+
+# 14. Narrow validation policy
+
+Run only the narrowest checks that prove the change:
+
+- Bash files: `bash -n <file>` and `shellcheck <file>` when ShellCheck is available.
+- POSIX shell files: `sh -n <file>`.
+- CLI or parser changes: the safest available help/parser check, if the environment permits it without performing installer
+  actions.
+- YAML/preseed changes: parse or validate the changed file with repository tooling if a cheap parser or validator is present.
+- Python files: run the relevant checks configured under `py/`, such as Ruff, mypy, or pytest, when applicable.
+- Documentation-only changes: confirm the target files exist, check the final diff, and run Markdown linting only when the
+  repository has a cheap configured Markdown lint command.
+
+Do not run full installer builds, debootstrap, destructive disk tests, broad repository audits, or network-heavy validation
+unless explicitly requested or technically required to validate the change.
+
+If a relevant check cannot be run, state the exact reason, and the command that should be run locally.
+
+# 15. Code review
+
+Reviews follow `code_review.md`.
 
 ---
 **[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**