V8.00.000.2025.06.17

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

func/cdi_1000_helper/README_1080.md

@@ -0,0 +1,138 @@
+---
+gitea: none
+include_toc: true
+---
+
+# 1. CISS.debian.installer
+
+**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>
+
+# 2. [1080_helper_chroot.sh](1080_helper_chroot.sh)
+**Scope:** This note explains *what to use when* among
+* `chroot_exec()`, 
+* `chroot_script()`, and 
+* `chroot_stdin()`.
+
+
+## 2.1. When to use what
+
+- **`chroot_exec (target, argv...)`** — *Simple, argv-style commands.*  
+  Use it whenever you type a short command with discrete arguments (no shell features).  
+  Examples from the updated user provisioning flow: `getent`, `groupadd`, `useradd`, `usermod`, `chsh`.
+
+- **`chroot_script (target, "shell pipeline | redir && control-flow")`** — *Anything that needs a shell.*  
+  Use it for pipelines, redirections, variable expansions, conditionals/loops, or tools that **expect** to run under a shell
+  (e.g., `visudo` with `EDITOR=...`, `logrotate -d ... >> logfile`).
+
+- **`chroot_stdin (target) <<'EOF' ... EOF`** — *Long, multi-line payloads without argv/ARG_MAX pain.*  
+  Use it to stream robust, quoting-safe scripts via **stdin** (`bash -s`). Ideal for multi-line `awk`/`sed` edits, or any 
+  content that would otherwise suffer from nested quoting or size limits if passed via `-c`. The helper sets up `bash -s` with 
+  strict shell options; ones provide the payload on stdin.
+
+All three helpers run with a *minimal, deterministic* environment via `env -i`, reintroducing only:
+* `HOME`,
+* `PATH`,
+* `TERM`,
+* `LANG/LC_ALL`, and 
+* noninteractive APT settings. 
+This ensures reproducibility and reduces the risk of ambient-environment leakage.
+
+## 2.2. Design rationale
+
+### 2.2.1. `chroot_exec()` — argv purity, preflight, the least overhead
+**Best for:** idempotent system administration commands that do not require shell parsing.
+
+**Key traits**
+- **Preflight binary presence** with `which` inside the chroot before running the command — early, clear failure if a package 
+  was not installed yet.
+- **Sanitized environment** (`env -i` with a strict default PATH and essential variables) for deterministic behavior.
+- **Straight argv execution** — no shell interpretation; no quoting games.
+
+**When _not_ to use**  
+If you need a pipe, a redirect, variable expansion, or inline control flow — switch to `chroot_script` 
+(or `chroot_stdin` for long fragments).
+
+### 2.2.2. `chroot_script()` — controlled shell, explicit `-c`
+**Best for:** single-line pipelines and short shell snippets.
+
+**Key traits**
+- Launches `/bin/bash` with strict options: `errexit`, `errtrace`, `functrace`, `nounset`, `pipefail`, plus Bash options
+  `inherit_errexit`, `failglob`, `lastpipe`. This makes subtle failures visible and prevents masked errors in pipelines.
+- Same **minimal environment** as `chroot_exec()`.
+- **Debug path**: on failure and if debugging flags are enabled, it drops into an interactive shell in the chroot for immediate
+  triage.
+
+**Trade-offs**
+- The entire snippet becomes **one long argument** to `bash -c`. Very long or quote-dense payloads hit **`argv+env` limits** 
+and are harder to lint. Prefer `chroot_stdin` for larger edits.
+
+### 2.2.3 `chroot_stdin()` — robust multi-line scripts via `bash -s`
+**Best for:** complex, multi-line payloads (Heredoc), quoting-heavy `awk`/`sed` programs, or anything beyond a small snippet.
+
+**Key traits**
+- Uses `bash -s` under the same strict shell options as `chroot_script`, but reads the script from **stdin**.
+- Avoids **`argv`** size and **'ARG_MAX'** constraints entirely; ideal for longer program fragments.
+- Greatly simplifies quoting: with a **single-quoted** heredoc (`<<'EOF'`) in the caller, you eliminate shell expansion 
+  surprises and keep editors/IDEs happy.
+
+## 2.3. Common foundation across all helpers
+
+- **Minimal, controlled environment via `env -i`**, whitelisting only the necessities (`HOME`, `PATH`, `TERM`, `LANG/LC_ALL`, 
+  noninteractive APT vars). This blocks noisy caller environments from leaking into the chroot and keeps behavior reproducible 
+  across systems. 
+- **Strict Bash modes** in the shell-based helpers — the effective default for the installer — to fail fast and surface latent 
+  errors. 
+- **Structured logging** for both success and failure paths, and an **interactive debug shell** when requested by the debug flags.
+
+## 2.4. Decision guide
+
+- **Is it a single command with clean argv?** → `chroot_exec`.
+- **Is it a short shell line with redirection/pipe/env assignment?** → `chroot_script`.
+- **Is it long, quote-heavy, or multi-line logic?** → `chroot_stdin` with a single-quoted heredoc.
+
+If in doubt, start with `chroot_exec`. The moment you need a shell feature, jump to `chroot_script`. If your `-c` string grows
+past comfort (readability, quoting, or length), upgrade to `chroot_stdin`.
+
+## 2.5. Subtleties and gotchas (and how the helpers address them)
+
+- **ARG_MAX and long `-c` strings:** `bash -c` places the entire script in `argv`. On typical Linux systems you effectively have
+  ≈2 MiB for argv+env; very long strings or large environments hit `E2BIG`. `bash -s` (stdin) avoids this entirely.
+
+- **Quoting pitfalls:** Nested single quotes within single-quoted strings become painful; Heredoc's with `<<'EOF'` (stdin) 
+  eliminate accidental expansions and simplify review.
+
+- **Locale-sensitive regex:** Always set `LC_ALL=C` for tools like `awk` to get predictable `[[:class:]]` semantics and bytewise
+  collation in system config edits.
+
+- **Partially writes / truncated files:** When editing files, write to a `*.new` and then `mv -f` only after `test -s` (non-empty)
+  to guard against empty outputs in case of earlier errors.
+
+- **Debug ergonomics:** The helpers integrate a conditional drop-in shell on failures when `VAR_CHROOT_DEBUG` (and related flags)
+  is enabled, enabling immediate forensics inside the target environment.
+
+## 2.6. Antipatterns (what to avoid)
+
+- **Using `chroot_exec` for anything involving the shell.** That defeats the argv-only contract and will either fail or behave unexpectedly.
+- **Packing large scripts into `-c` strings.** Hard to quote, hits argv limits, and clutters process lists. Prefer stdin.
+- **Relying on the caller’s ambient environment.** The helpers intentionally use `env -i` to avoid such a leakage; do not
+  reintroduce it unless you must.
+
+# 3. Appendix — Helper signatures & guarantees
+
+- **`chroot_exec(target, argv...)`**
+  - Preflights the binary using `which` inside the chroot; fails early if missing.
+  - Runs with a minimal, deterministic environment.
+
+- **`chroot_script(target, "code", [loglevel])`**
+  - Executes `bash -c "code"` under strict bash options; minimal environment; rich failure logging and optional interactive debug.
+
+- **`chroot_stdin(target, "marker", [loglevel]) <<'EOF' ... EOF`**
+  - Executes `bash -s` under strict bash options; minimal environment; same debug path; payload read from stdin, avoiding 
+    argv/ARG_MAX issues.
+
+---
+**[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**
+<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->