V8.00.000.2025.06.17

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

func/cdi_1000_helper/README/README_1080.md

@@ -10,15 +10,13 @@ include_toc: true
 **Master Version**: 8.00<br>
 **Build**: V8.00.000.2025.06.17<br>
 
-# 2. [1080_helper_chroot.sh](1080_helper_chroot.sh)
+# 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`.
@@ -79,7 +77,6 @@ and are harder to lint. Prefer `chroot_stdin` for larger edits.
   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. 
@@ -88,7 +85,6 @@ and are harder to lint. Prefer `chroot_stdin` for larger edits.
 - **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.
@@ -97,7 +93,6 @@ If in doubt, start with `chroot_exec`. The moment you need a shell feature, jump
 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.
 
@@ -114,14 +109,12 @@ past comfort (readability, quoting, or length), upgrade to `chroot_stdin`.
   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.

func/cdi_4000_debootstrap/README/README_4000.md

@@ -0,0 +1,101 @@
+---
+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. [4000_debootstrap.sh](../4000_debootstrap.sh)
+This module provisions a minimal Debian userspace into the installers target root (`$TARGET`) using `debootstrap`.
+It encapsulates argument construction, execution, logging, and the controlled hand-off of the `/debootstrap` working tree into a
+private, permissions-hardened folder under `root/.ciss/cdi/`.
+
+## 2.1. Responsibilities
+- Resolve architecture, distribution codename, mirror, and optionally include-set from the global environment.
+- Execute `debootstrap` with deterministic flags (`--keep-debootstrap-dir`, `--log-extra-deps`, `--merged-usr`) and optional `--include=`.
+- Stream all `debootstrap` output to a dedicated log (`$LOG_DBS`) for reproducibility and forensics.
+- Post-provisioning: create a sealed directory hierarchy beneath `$TARGET/root/.ciss/cdi/` and relocate the working directory 
+  from `$TARGET/debootstrap` to `$TARGET/root/.ciss/cdi/debootstrap`.
+- Emit structured progress diagnostics via the common logging facility.
+- Return a specific non-zero error code on failure to enable consistent trap-level handling.
+
+## 2.2. Inputs & Globals
+- **`$VAR_ARCHITECTURE`** — target architecture (e.g., `amd64`, `arm64`).
+- **`$VAR_CODENAME`** — Debian release codename (e.g., `trixie`).
+- **`$debootstrap_mirror`** — HTTP/HTTPS mirror base URL.
+- **`$debootstrap_includes`** — comma-separated package list to seed into the base system (optional).
+- **`$TARGET`** — absolute mount path of the target root filesystem.
+- **`$LOG_DBS`** — file path to receive `debootstrap` combined output via `tee`.
+- **`ERR_DEBOOTSTRAP`** — module-specific error code for uniform failure signaling.
+
+> All variables are expected to be pre-validated and exported by the installer setup/bootstrap chain.
+
+## 2.3. Execution Flow
+* **Command assembly**
+  - Build `ary_cmd` as:
+    ```
+    debootstrap \
+      --arch="${VAR_ARCHITECTURE}" \
+      --keep-debootstrap-dir \
+      --log-extra-deps \
+      --merged-usr \
+      [--include="${debootstrap_includes}"] \
+      "${VAR_CODENAME}" "${TARGET}" "${debootstrap_mirror}"
+    ```
+  - Emit a debug log line with the fully materialized command.
+
+* **Run & log**
+  - Execute the array-form command; pipe stdout/stderr to `$LOG_DBS` using `tee`.
+  - On success, emit an informational log entry; on failure, emit an emergency log and `return ${ERR_DEBOOTSTRAP}`.
+
+* **Post-provisioning layout (on success)**
+  - Create (mode `0700`, owned by `root:root`) under `$TARGET/root/.ciss/cdi/`:
+    - `backup/`, `debootstrap/`, `hooks/`, `keys/`, `log/`
+  - Move the working directory:
+    - `mv -T "$TARGET/debootstrap" "$TARGET/root/.ciss/cdi/debootstrap"`
+  - Reassert restrictive permissions on `.ciss/`, `.ciss/cdi/`, and `.ciss/cdi/debootstrap/`.
+  - Invoke `guard_dir` (module guard) and return `0`.
+
+## 2.4. Design Paradigms
+- **Array-based invocation**: Prevents word-splitting and globbing pitfalls; arguments are passed verbatim to `execve`.
+- **Deterministic defaults**:
+  - `--merged-usr`: aligns the base system with usrmerge conventions (Debian ≥ 12).
+  - `--keep-debootstrap-dir`: preserves provenance and the exact state of the bootstrap transaction.
+  - `--log-extra-deps`: surfaces additional dependency resolution in logs for auditability.
+- **Fail-fast and traceable**: Execution is meant to run under global hardening (`set -Ceuo pipefail`, `inherit_errexit`) and 
+  integrates with the installer trap/debug framework; logs are persisted for triage.
+
+## 2.5. Security Considerations
+- **Least exposure of artifacts**: The bootstrap working directory is relocated into a sealed, root-only area (`0700`).
+  This avoids exposing transient metadata under world-readable paths.
+- **No shell expansion in command string**: Array execution and explicit variables reduce injection risk and ambiguity.
+- **Privilege hygiene**: Directory creation and moves are executed with explicit ownership/mode; no reliance on ambient umask.
+- **Provenance retention**: Keeping the original `debootstrap` directory (under a protected path) allows later verification of
+  package selection, scripts, and logs.
+
+## 2.6. Logging & Artifacts
+- **Primary log**: `${LOG_DBS}` receives the raw `debootstrap` stream (via `tee`).
+- **Provenance**: `${TARGET}/root/.ciss/cdi/debootstrap/` contains the retained working directory after a successful run.
+- **Installer meta-folders**: `${TARGET}/root/.ciss/cdi/{backup,debootstrap,hooks,keys,log}/` (all `0700`).
+
+These artifacts integrate with the global debug facilities when enabled.
+
+## 2.7. Failure Modes & Exit Codes
+- **Network or mirror failure** → non-zero `debootstrap` exit → module returns `ERR_DEBOOTSTRAP`.
+- **Invalid codename/arch** → early `debootstrap` abort → `ERR_DEBOOTSTRAP`.
+- **Insufficient permissions or target not writable** → directory creation/move fails → `ERR_DEBOOTSTRAP`.
+
+Errors are surfaced to the installers `ERR`/`EXIT` traps, which will record environment, stack, and runtime context.
+
+## 2.8. Best Practices
+- Use `--include` judiciously; keep the base system minimal and defer optional packages to dedicated post-bootstrap tasks.
+- Treat `${TARGET}/root/.ciss/cdi/` as sensitive metadata: back it up or snapshot it if you require later audits.
+
+---
+**[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 -->

var/README/README_BASH_VAR.md

@@ -0,0 +1,99 @@
+---
+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. [bash.var.sh](../bash.var.sh)
+This module establishes the global execution profile for all modules of the `CISS.debian.installer`. It is sourced at the very 
+beginning of the installer lifecycle to impose strict, deterministic shell semantics, to minimize ambiguity in expansions, and 
+to reduce the attack surface inherent to shell scripting. The profile complements the project-wide trap and debugging
+infrastructure and applies uniformly to subshells and functions.
+
+## 2.1. Scope and Guarantees
+- Enforces fail-fast error semantics across functions and subshells.
+- Normalizes filename expansion and word-splitting to safe defaults.
+- Constrains the effective runtime search path (`PATH`) to trusted system locations.
+- Establishes a conservative file creation policy (`umask 0022`).
+- Avoids reliance on interactive shell artifacts (aliases, dotglob, nullglob).
+- Ensures consistent behaviour for pipelines and command substitutions.
+
+## 2.2. Execution Settings (`set -o ...`)
+
+| Option      | Effect (Rationale)                                                                                     |
+|-------------|--------------------------------------------------------------------------------------------------------|
+| `errexit`   | Abort on any non-zero exit status. Prevents silent continuation after failed steps.                    |
+| `errtrace`  | Inherit `ERR` traps in functions/subshells. Ensures uniform error handling depth-wise.                 |
+| `functrace` | Inherit `DEBUG`/`RETURN` traps. Enables deep stack and step tracing when debug facilities are enabled. |
+| `ignoreeof` | Suppress accidental exit on `EOF` (Ctrl-D) in interactive contexts.                                    |
+| `noclobber` | Disallow redirections from overwriting existing files. Reduces risk of destructive writes.             |
+| `nounset`   | Treat use of unset variables as fatal. Surfaces programming defects immediately.                       |
+| `pipefail`  | Pipeline returns the first non-zero exit code. Eliminates false positives in multi-stage pipelines.    |
+
+> These options are intended to run in concert; changing one (e.g., disabling `nounset`) undermines the overall guarantee set.
+
+## 2.3. Bash Operational Settings (`shopt ...`)
+
+| Option            | State | Effect (Rationale)                                                                                                 |
+|-------------------|-------|--------------------------------------------------------------------------------------------------------------------|
+| `failglob`        | `on`  | Globs that match nothing raise an error instead of passing a literal. Prevents unintended mass operations.         |
+| `inherit_errexit` | `on`  | Preserves `errexit` in command substitutions. Prevents subshells from masking failures.                            |
+| `lastpipe`        | `on`  | When job control is off, the last pipeline command runs in the current shell. Allows variable assignment in place. |
+| `expand_aliases`  | `off` | Disables alias expansion in non-interactive execution. Ensures parse-time predictability.                          |
+| `dotglob`         | `off` | Excludes dotfiles from globbing unless explicitly requested. Reduces accidental inclusion of hidden state.         |
+| `extglob`         | `off` | Disables extended pattern operators by default. Avoids syntactic ambiguity; enable locally if strictly required.   |
+| `nullglob`        | `off` | Non-matching globs do not vanish to empty strings. Preserves error signalling pathways.                            |
+
+
+## 2.4. Environment Normalisation
+
+- **`PATH`** `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` Restricts execution to canonical system directories 
+  and avoids user-writable or ephemeral locations.
+- **`IFS`**  `space, tab, newline` Resets the internal field separator to the safe triplet, mitigating word-splitting injections
+  and parsing anomalies.
+- **`umask`** `0022` Files are world-readable by default but only owner-writable; directories are owner-writable/executable.
+  This aligns with conservative system defaults while avoiding accidental over-permission.
+
+## 2.5. Design Paradigms
+- **Deterministic failure**: The profile is built around immediate error surfacing and uniform propagation into traps and 
+  subshells.
+- **Minimal ambient state**: Aliases and risky globbing behaviors are disabled to reduce hidden semantics and side effects.
+- **Explicitness first**: Module code is expected to prefer explicit redirections, explicit globbing, and explicit function 
+  variable declarations (`declare`, `declare -g` for globals).
+- **Composability**: Settings are chosen to interoperate cleanly with the installers `ERR`, `EXIT`, `INT`, and optional
+  `DEBUG` `XTRACE` subsystems.
+
+## 2.6. Interaction with TRAP/DEBUG Subsystem (Brief)
+
+- `errtrace` and `functrace` ensure that `ERR` and `DEBUG` handlers fire consistently in nested contexts, enabling accurate 
+  stack and command logging.
+- `nounset` guarantees that unbound variable faults propagate as hard failures, which are then recorded by the `EXIT` trap 
+  (covering cases not seen by `ERR`).
+- `pipefail` produces truthful failure points for `ERR` to capture in multi-stage pipelines.
+
+## 2.7. Security Considerations
+
+- **Search path integrity**: A reduced, fixed `PATH` avoids resolving executables from untrusted paths (e.g., pwd, temp).
+- **Write-safety**: `noclobber` and a conservative `umask` reduce both accidental and adversarial overwrites.
+- **Predictable expansion**: `failglob`, `dotglob`, and `nullglob` settings ensure globs behave loudly on errors and never 
+  silently widen or narrow scope.
+- **Secret hygiene**: In combination with the debug modules, sensitive data is not exposed through uncontrolled expansions or
+  unset variables.
+
+## 2.8. Best Practices
+- **Scope deviations locally**: If a module must enable `extglob` or relax an option, do so in the narrowest possible lexical 
+  scope and restore the default immediately afterward.
+- **Avoid reliance on aliases**: Prefer explicit functions or scripts with fully qualified paths.
+- **Validate assumptions**: When using pipelines or command substitutions, assume `pipefail`/`inherit_errexit` semantics and 
+  handle errors accordingly.
+- **Pair with traps**: Always run under the project trap handlers to obtain structured diagnostics on failure.
+
+---
+**[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 -->