diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..8fd2e66 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,68 @@ +# SPDX-FileCopyrightText: 2025-2026 VectoDE +# +# SPDX-License-Identifier: MIT + +# The website: built from the module metadata by scripts/build-site.sh and held to Lighthouse 100 in every category +# on every pull request and push to main; deployed to GitHub Pages only from main. The page is never committed, so a +# new module is on the site with the next deploy. +name: Pages + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: pages-${{ github.ref }} + # A deploy that has started finishes; pull request runs make way for newer commits. + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +jobs: + build: + name: Build and Lighthouse + runs-on: ubuntu-24.04 + timeout-minutes: 15 + steps: + - uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Build + # Also fails when the README tables differ from data/systems.conf. + run: scripts/build-site.sh _site + - name: Lighthouse + uses: treosh/lighthouse-ci-action@3e7e23fb74242897f95c0ba9cabad3d0227b9b18 # 12.6.2 + with: + configPath: site/lighthouserc.json + uploadArtifacts: true + temporaryPublicStorage: false + - name: Upload the site for Pages + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: _site + + deploy: + name: Deploy + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + needs: build + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1 + with: + egress-policy: audit + - id: deployment + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 diff --git a/.gitignore b/.gitignore index a9ec1ec..66908fd 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ # Local Claude Code data (worktrees, settings) .claude/ + +# Website build output (scripts/build-site.sh) +_site/ diff --git a/.sonarcloud.properties b/.sonarcloud.properties index 21173e3..5620267 100644 --- a/.sonarcloud.properties +++ b/.sonarcloud.properties @@ -3,7 +3,7 @@ # SPDX-License-Identifier: MIT # SonarQube Cloud automatic analysis reads this file: https://sonarcloud.io/project/overview?id=VectoDE_Linux-Server-Setup-Script -sonar.sources=lss,lib,libexec,modules,scripts,install-configure-script.bash +sonar.sources=lss,lib,libexec,modules,scripts,site,install-configure-script.bash sonar.tests=tests # Accepted findings, each with its reason. diff --git a/CHANGELOG.md b/CHANGELOG.md index e5aa3d0..d65ac41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -88,6 +88,10 @@ now or later. its results for Prometheus through the node exporter. - The services of the backup, monitoring and network modules run with a systemd sandbox drop-in; a service that listens on the WireGuard address starts after the interface. +- Website on GitHub Pages: lss explained as a film that plays while scrolling, generated from the module metadata, + the profiles and `data/systems.conf` on every deploy. A field of packets drawn on a canvas closes into a shield + while the module groups pass. Strict Content Security Policy, a still version for reduced motion and Lighthouse + 100 checked in CI. ### Removed diff --git a/README.md b/README.md index 5ffdbb8..6a986d9 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,8 @@ row is the cost of the whole set, including the web server or PHP it needs. time and the peak memory go. Later runs reuse the build. The integration jobs print these figures as `RESOURCES` lines, so every new module and every new system adds its own. +The tables "Supported systems" and "System requirements" above come from `data/systems.conf`, which the website reads +too; CI fails when they differ. ## Quick start @@ -499,6 +501,7 @@ well, where an alert rule picks it up. - [Troubleshooting](docs/troubleshooting.md): locked out, failed modules, common messages - [Assurance case](docs/assurance.md): threat model, trust boundaries and how lss counters common weaknesses - [Writing a module](docs/module-guide.md) +- [Website](docs/website.md): the scroll film on GitHub Pages, built from the module files - [Changelog](CHANGELOG.md) ## Contributing and security diff --git a/REUSE.toml b/REUSE.toml index cac0518..fc09087 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -11,6 +11,7 @@ path = [ ".github/CODEOWNERS", ".github/allowed_signers", "templates/**", + "site/lighthouserc.json", "tests/fixtures/os-release/**", ] SPDX-FileCopyrightText = "2025-2026 VectoDE" diff --git a/data/systems.conf b/data/systems.conf new file mode 100644 index 0000000..9e537d9 --- /dev/null +++ b/data/systems.conf @@ -0,0 +1,28 @@ +# SPDX-FileCopyrightText: 2025-2026 VectoDE +# +# SPDX-License-Identifier: MIT + +# Supported systems and what lss needs to run on them. One source for the tables "Supported systems" and "System +# requirements" in README.md and for the website: scripts/build-site.sh renders the website from it, and +# `scripts/build-site.sh --check` (run in CI) fails when the README tables say something else. +# +# Fields are separated by "|". Text in backticks is shown as code. +# +# system||| +# arch| +# requirement|||| +# +# The requirement figures come from the RESOURCES lines of the integration jobs (tests/integration/run.sh): the +# largest value across the tested systems, rounded up. + +system|Debian|12, 13|12, 13 +system|Ubuntu|22.04, 24.04, 26.04|22.04, 24.04, 26.04 +system|Rocky Linux, AlmaLinux, RHEL|9, 10|Rocky 9, AlmaLinux 10 + +arch|x86_64 and arm64 (aarch64). CI runs on x86_64: on every pull request it installs, verifies, installs again and removes every module on each tested system. + +requirement|Profile `minimal-secure`|1 GB; 2 GB on the RHEL family|4 GB|3 to 5 min plus AIDE +requirement|`minimal-secure` with `crowdsec`|1.5 GB; 2 GB on the RHEL family|4.5 GB|about 30 s more +requirement|`minimal-secure` with `clamav`|2.5 GB|4.5 GB|about 1 min more +requirement|Profile `office`|1.5 GB; 2 GB on the RHEL family|10 GB|9 to 16 min +requirement|Profile `devops`|1 GB; 1.5 GB on the RHEL family|7 GB|6 to 11 min diff --git a/docs/website.md b/docs/website.md new file mode 100644 index 0000000..cf2451b --- /dev/null +++ b/docs/website.md @@ -0,0 +1,108 @@ +# Website + +The website explains lss as a film that plays while you scroll: every scene sticks to the screen while its lines +appear, its list rolls past or its items change, with a caption at the bottom. It is one static page on GitHub +Pages, built from the repository on every deploy. + +## What it is built from + +`scripts/build-site.sh` writes the page and reads everything it shows from the repository: + +| On the page | Source | +| ------------------------------------- | ------------------------------------------------------------------------ | +| One scene per module group | `MOD_NAME`, `MOD_GROUP`, `MOD_DESCRIPTION`, `MOD_CONFLICTS` and `MOD_OPTIONS` of every module (sourced in a subshell, like `lss info`) | +| The order of an example run | `MOD_REQUIRES` | +| Profiles | `profiles/*.conf` (`# Profile:` line and `LSS_MODULES`) | +| Guard time and thresholds | the defaults in `MOD_OPTIONS` of `guard` | +| `lss --help` | the `usage` function of `lss` | +| The menu | `ui_menu` in `lib/ui.sh` | +| Supported systems, requirements | `data/systems.conf` | +| Version | `VERSION` | + +A new module, group or profile is on the site with the next deploy; nobody edits the page. A group the generator +does not know yet gets a scene with a plain caption after the known groups. The captions of the known groups, the +security model and the verified install are written in the generator. + +`data/systems.conf` is also the source of the tables "Supported systems" and "System requirements" in the README: +`scripts/build-site.sh --check` (part of every build, so part of CI) fails when they say something else. Change +both together. + +## Build and preview + +```bash +scripts/build-site.sh _site # writes _site/index.html, film.js, favicon.svg and robots.txt +python3 -m http.server -d _site 8000 # any static server will do +``` + +`_site/` is not committed. The page is generated in the Pages workflow (`.github/workflows/pages.yml`), so it +cannot fall behind the modules, and a pull request shows the result of its own changes. + +## Motion, keyboard and screen readers + +Every word of every scene is in the HTML from the start. `site/film.js` only moves and marks it: it sets the scene +counter, shows lines, rolls the stage and highlights the current item. What moves while you scroll: + +| Scene | Motion | +| ---------------------- | ---------------------------------------------------------------------------------------- | +| Opening | The title steps back and shrinks; the counts of modules, groups, profiles and tested systems run up from 0 once after loading | +| Every scene | The words of the heading rise out of their masks as it scrolls in; the caption comes in word by word (opacity and blur) | +| A run | Log lines appear one by one, the newest marked, and the log rolls like a terminal | +| Profiles, menu | One profile or menu item at a time | +| Module groups | The list rolls past and the current module is marked | +| Run to last group | Packets drifting across the screen leave their lines in random order and close into a shield with "lss" cut out | +| Guard | A scan line sweeps over the shield | +| After the guard | The field fades out and stops drawing | + +The field is a 2D canvas behind the text, drawn by `film.js` without a library. It starts after the page has +loaded, stops in hidden tabs and once it has faded out, and draws at most at 1.5 times the CSS resolution. On +screens narrower than 900 px the shield sits behind the text and is drawn at half the strength. The scatter of the +packets comes from a fixed seed, so the page looks the same on every visit. The heading masks use CSS +scroll-driven animations (`animation-timeline: view()`) where the browser has them; elsewhere `film.js` raises them +when the heading comes into view, and without the script they stay where they are. Scrolling is the browser's own: +nothing takes over the wheel, keys, find in page or anchors. The film needs motion allowed +(`prefers-reduced-motion: no-preference`), scripting and a screen at least 30rem tall. Otherwise the same scenes +are a still sequence of full-screen frames, with nothing hidden. + +The chapter list in the header jumps to every scene, a skip link leads to the film, and focus is always visible. +Decoration (scene numbers on the splice line, the counter, the progress bar) is hidden from screen readers; the +headings, captions, lists and tables are plain HTML. + +Colour has one meaning: yellow marks what lss is doing right now, red what it refuses or what failed. The palette +is checked against WCAG AA in light and dark mode. The fonts are the system's own monospace and sans-serif. + +## Content Security Policy and headers + +The page loads nothing from other servers: no fonts, no analytics, no cookies. Its policy, set by a meta tag: + +```text +default-src 'none'; script-src 'self'; style-src 'sha256-'; img-src 'self'; +connect-src 'self'; base-uri 'none'; form-action 'none' +``` + +The page itself makes no requests after loading; `connect-src 'self'` is there for tools that fetch `robots.txt` +of the same site from within the page, such as Lighthouse. + +The stylesheet is inlined to save a request and allowed by its SHA-256, which the generator computes on every +build; there are no style attributes and no inline scripts. GitHub Pages cannot set response headers. A host that +can should send these as well (a meta tag cannot carry `frame-ancestors`): + +```text +Content-Security-Policy: default-src 'none'; script-src 'self'; style-src 'sha256-...'; img-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none' +X-Content-Type-Options: nosniff +Referrer-Policy: no-referrer +Permissions-Policy: camera=(), microphone=(), geolocation=() +Cross-Origin-Opener-Policy: same-origin +``` + +## Checks + +The Pages workflow builds the page and runs Lighthouse (three runs, mobile settings) on every pull request and push +to `main`. It fails below 100 in any of performance, accessibility, best practices and SEO. The unit tests in +`tests/unit/site.bats` check that every module, group and profile is on the page, that the policy hash matches the +stylesheet and that the page has no external resources. + +## Deploy + +Only a push to `main` deploys, through `actions/upload-pages-artifact` and `actions/deploy-pages` with +`pages: write` and `id-token: write` for that job alone. GitHub Pages has to be enabled once in the repository +settings with the source "GitHub Actions". diff --git a/scripts/build-site.sh b/scripts/build-site.sh new file mode 100755 index 0000000..97481ea --- /dev/null +++ b/scripts/build-site.sh @@ -0,0 +1,758 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: 2025-2026 VectoDE +# +# SPDX-License-Identifier: MIT + +# Builds the website, a film of full-screen scenes that plays while scrolling: +# +# scripts/build-site.sh [OUT_DIR] write index.html, film.js, favicon.svg and robots.txt to OUT_DIR (default _site) +# scripts/build-site.sh --check only compare the README tables with data/systems.conf +# +# The text comes from the repository itself: MOD_NAME, MOD_GROUP, MOD_DESCRIPTION, MOD_REQUIRES, MOD_CONFLICTS and +# MOD_OPTIONS of every module, the profiles, data/systems.conf, the help text of lss and the menu items of lib/ui.sh. +# The Pages workflow runs this on every deploy and the page is never committed, so a new module or profile is on the +# site with the next deploy. The stylesheet is inlined and allowed by its SHA-256 in the Content Security Policy; +# film.js is the only script. +set -Eeuo pipefail +shopt -s inherit_errexit +cd "$(dirname "${BASH_SOURCE[0]}")/.." + +SITE_SRC=site +SYSTEMS=data/systems.conf +REPO_URL=https://github.com/VectoDE/Linux-Server-Setup-Script +read -r LSS_SITE_VERSION &2 + exit 1 +} + +# The text helpers assign to a variable named by the caller instead of printing: every command substitution costs a +# fork, and the page has a few thousand values. + +# esc VAR TEXT: VAR is TEXT with the HTML special characters escaped. The quoted replacements keep "&" literal in +# bash 5.2. +esc() { + local -n _esc_out=$1 + local _esc_text=$2 + _esc_text=${_esc_text//'&'/'&'} + _esc_text=${_esc_text//'<'/'<'} + _esc_text=${_esc_text//'>'/'>'} + _esc_text=${_esc_text//'"'/'"'} + _esc_out=${_esc_text} + return +} + +# inline VAR TEXT: VAR is the escaped TEXT with `code` spans as . +inline() { + local -n _inline_out=$1 + local _inline_source=$2 + # shellcheck disable=SC2016 # literal backticks, nothing to expand + local _inline_text _inline_html="" _inline_re='^([^`]*)`([^`]*)`(.*)$' + esc _inline_text "${_inline_source}" + while [[ ${_inline_text} =~ ${_inline_re} ]]; do + _inline_html+="${BASH_REMATCH[1]}${BASH_REMATCH[2]}" + _inline_text=${BASH_REMATCH[3]} + done + _inline_out=${_inline_html}${_inline_text} + return +} + +# --- sources ------------------------------------------------------------------------------------------------------ + +# Prints the metadata of every module, read the way lss reads it (module_meta): this runs in a subshell, which sources +# the module files one after the other, so nothing of them reaches the rest of the script. Records end with \x1e, +# fields are separated by \x1f. +read_metadata() { + set +eu + export LSS_ROOT=${PWD} + local file + for file in modules/*/*.sh; do + unset MOD_NAME MOD_GROUP MOD_DESCRIPTION MOD_REQUIRES MOD_CONFLICTS MOD_OPTIONS + # shellcheck source=/dev/null + source "${file}" >/dev/null 2>&1 + printf '%s\x1f%s\x1f%s\x1f%s\x1f%s\x1f%s\x1f%s\x1e' "${file}" "${MOD_NAME-}" "${MOD_GROUP-}" \ + "${MOD_DESCRIPTION-}" "${MOD_REQUIRES-}" "${MOD_CONFLICTS-}" "${MOD_OPTIONS-}" + done + return 0 +} + +load_modules() { + local file name group desc requires conflicts options expected + while IFS=$'\x1f' read -r -d $'\x1e' file name group desc requires conflicts options; do + expected=${file##*/} + [[ ${name} == "${expected%.sh}" ]] || fail "${file}: MOD_NAME is '${name}'." + expected=${file%/*} + [[ ${group} == "${expected##*/}" ]] || fail "${file}: MOD_GROUP is '${group}'." + [[ -n ${desc} ]] || fail "${file}: MOD_DESCRIPTION is empty." + MODULES+=("${name}") + M_GROUP[${name}]=${group} + M_DESC[${name}]=${desc} + M_REQUIRES[${name}]=${requires} + M_CONFLICTS[${name}]=${conflicts} + M_OPTIONS[${name}]=${options} + done < <(read_metadata) + [[ ${#MODULES[@]} -gt 0 ]] || fail "modules/ has an empty module list." + local -A present=() + for name in "${MODULES[@]}"; do + present[${M_GROUP[${name}]}]=1 + done + for group in ${GROUP_ORDER}; do + if [[ -n ${present[${group}]-} ]]; then + GROUPS_SORTED+=("${group}") + unset 'present[${group}]' + fi + done + mapfile -t -O "${#GROUPS_SORTED[@]}" GROUPS_SORTED < <(printf '%s\n' "${!present[@]}" | sed '/^$/d' | sort) + return +} + +# option_default VAR MODULE OPTION: VAR is the default value of OPTION from MOD_OPTIONS. +option_default() { + local -n _default_out=$1 + local _od_module=$2 _od_option=$3 _od_name _od_default _ + while IFS='|' read -r _od_name _od_default _; do + if [[ ${_od_name} == "${_od_option}" ]]; then + _default_out=${_od_default} + return 0 + fi + done <<<"${M_OPTIONS[${_od_module}]}" + fail "${_od_module} has the option '${_od_option}' missing from MOD_OPTIONS." +} + +# install_order VAR MODULE...: VAR is the list of the modules with their requirements first, like module_resolve +# (the first of alternatives). +install_order() { + local -n _order_out=$1 + shift + local -A _seen=() + local -a _order=() + _visit() { + local name=$1 requirement + [[ -z ${_seen[${name}]-} ]] || return 0 + _seen[${name}]=1 + for requirement in ${M_REQUIRES[${name}]-}; do + _visit "${requirement%%|*}" + done + _order+=("${name}") + return + } + local name + for name in "$@"; do + _visit "${name}" + done + _order_out=${_order[*]} + return +} + +# profiles: "name|description|modules" per profile, the smallest first. +profiles() { + local file description modules name + local -a words=() + for file in profiles/*.conf; do + description=$(sed -n 's/^# Profile: //p' "${file}") + modules=$(sed -n 's/^LSS_MODULES=//p' "${file}") + [[ -n ${description} && -n ${modules} ]] || fail "${file} needs '# Profile:' and LSS_MODULES." + read -ra words <<<"${modules}" + name=${file##*/} + printf '%s %s|%s|%s\n' "${#words[@]}" "${name%.conf}" "${description}" "${modules}" + done | sort -n | cut -d' ' -f2- + return +} + +# The help text of `lss --help`, from the usage function of lss. +help_text() { + local text + text=$(sed -n '/^usage() {/,/^}/p' lss | sed -n '/cat < 2) print; next } + inside && rows > 0 { exit } + ' README.md | sed -e 's/^|[[:space:]]*//' -e 's/[[:space:]]*|[[:space:]]*$//' -e 's/[[:space:]]*|[[:space:]]*/|/g' + return +} + +check_readme() { + local status=0 + if ! diff <(systems_rows system) <(readme_rows "Supported systems") >&2; then + printf 'build-site: README.md "Supported systems" differs from the system lines of %s (above).\n' "${SYSTEMS}" >&2 + status=1 + fi + if ! diff <(systems_rows requirement) <(readme_rows "System requirements") >&2; then + printf 'build-site: README.md "System requirements" differs from the requirement lines of %s (above).\n' "${SYSTEMS}" >&2 + status=1 + fi + return "${status}" +} + +# --- scenes ------------------------------------------------------------------------------------------------------- + +# list_close TAG: the end of an ol or ul. +list_close() { + local tag=$1 + printf '\n' "${tag}" + return +} + +# scene_open ID TITLE KIND LENGTH: starts a scene. KIND tells film.js what the progress drives (steps: lines appear, +# roll: the stage rolls past, switch: one item at a time, hero: the title steps back, still: the stage only rolls +# when it is taller than the screen). LENGTH is the scroll length in screens, 1 to 6. +scene_open() { + local id=$1 title=$2 kind=$3 length=$4 number html + if ((length > 6)); then + length=6 + fi + SCENE_IDS+=("${id}") + SCENE_TITLES+=("${title}") + printf -v number '%02d' "${#SCENE_IDS[@]}" + esc html "${title}" + printf '
\n' \ + "${length}" "${id}" "${kind}" "${html}" "${id}" + printf '
\n\n' \ + "${number}" "${html}" + return +} + +# scene_close CAPTION: the caption (subtitle) of the scene and the end of it. +scene_close() { + local caption=$1 + printf '

%s

\n
\n
\n' "${caption}" + return +} + +stage_open() { + printf '
\n
\n' + return +} + +stage_close() { + printf '
\n
\n' + return +} + +# heading ID TEXT [PREFIX]: the h2 of a scene, every word in a mask of its own so that it can rise into view. PREFIX +# is shown muted in front of the text, like the "modules/" of a group. +heading() { + local id=$1 text=$2 prefix=${3:-} word html + local -a words=() + printf '

' "${id}" + if [[ -n ${prefix} ]]; then + esc html "${prefix}" + printf '%s' "${html}" + fi + read -ra words <<<"${text}" + for word in "${words[@]}"; do + esc html "${word}" + printf '%s ' "${html}" + done + printf '

\n' + return +} + +# count_tested: the number of releases data/systems.conf lists as tested in CI. +count_tested() { + local _distribution _releases tested count=0 + local -a releases=() + while IFS='|' read -r _distribution _releases tested; do + IFS=',' read -ra releases <<<"${tested}" + count=$((count + ${#releases[@]})) + done < <(systems_rows system) + printf '%s' "${count}" + return +} + +# counter NUMBER LABEL: one figure of the opening. +counter() { + local number=$1 label=$2 + printf '
%s
%s
\n' "${label}" "${number}" "${number}" + return +} + +scene_hero() { + local -a profile_files=(profiles/*.conf) + scene_open top "lss" hero 2 + cat <<'EOF' +

lssLinux Server Setup

+EOF + stage_open + cat <<'EOF' +

sudo lss install --profile minimal-secure

+

Sets up and hardens Linux servers from modules. Install a whole profile in one run, or only the +modules you need, and come back later to add, change or remove one.

+EOF + # Read from the repository on every build. The order of dt and dd is swapped visually, the number comes first. + printf '
\n' + counter "${#MODULES[@]}" modules + counter "${#GROUPS_SORTED[@]}" groups + counter "${#profile_files[@]}" profiles + counter "$(count_tested)" "systems tested in CI" + printf '
\n' + stage_close + scene_close "Scroll to play the film. Every scene is plain text, so it reads the same with motion turned off." + return +} + +log_line() { + local source_level=$1 source_text=$2 class=${3:-} level text + esc level "${source_level}" + inline text "${source_text}" + printf '
  • %s%s
    • \n' "${class:+ ${class}}" "${level}" "${text}" + return +} + +scene_run() { + local order name last + install_order order firewall fail2ban + last=${order##* } + scene_open run "A run" steps 3 + heading run "One module at a time" + stage_open + printf '
      \n' + log_line '$' 'sudo lss install firewall fail2ban' cmdline + log_line INFO "Modules in order: ${order}" + for name in ${order}; do + log_line '==>' "${name}" + if [[ ${name} == "${last}" ]]; then + log_line OK "${name}: done (6 changes)" ok + elif [[ ${name} == system ]]; then + log_line OK "${name}: unchanged" ok + else + log_line OK "${name}: done (3 changes)" ok + fi + done + log_line OK 'Finished. Log: /var/log/lss/.log' ok + printf '
    \n

    When a step fails

    \n
      \n' + log_line '==>' "${last}" + log_line ERROR "${last}: verification failed; changed files were restored. Details: /var/log/lss/.log" deny + list_close ol + stage_close + scene_close "Each module checks its settings before it changes anything. When a step fails, lss puts back every +file that module touched in the run. Later, lss verify shows whether it still works." + return +} + +scene_profiles() { + local -a rows=() + local row name description modules html + local -a words=() + mapfile -t rows < <(profiles) + scene_open profiles "Profiles" switch "${#rows[@]}" + heading profiles "${#rows[@]} profiles" + stage_open + printf '
      \n\n
      \n' + for row in "${rows[@]}"; do + IFS='|' read -r name description modules <<<"${row}" + esc name "${name}" + inline description "${description}" + esc modules "${modules}" + read -ra words <<<"${modules}" + # One span per module keeps "kernel-hardening" on one line. + printf -v modules '%s ' "${words[@]}" + printf '
      \n

      %s

      \n

      %s

      \n' "${name}" "${description}" + printf '

      %s modules, in this order

      \n

      %s

      \n
      \n' \ + "${#words[@]}" "${modules}" + done + printf '
      \n
      \n' + stage_close + scene_close "A profile is a list of modules for one kind of server. Start from one, then add or remove single +modules with lss install and lss remove." + return +} + +group_caption() { + local group=$1 + case ${group} in + base) printf 'The ground floor: host name, locale and updates, time over NTS, swap, the administrator account, tools and a persistent journal.' ;; + security) printf 'The hardening and the checks that keep it in place. One of fail2ban and CrowdSec; ssh-2fa, clamav and usbguard are opt-in.' ;; + web) printf 'One web server owns ports 80 and 443, HTTPS only, with certificates from Let's Encrypt and sites from a single setting.' ;; + runtime) printf 'Language runtimes from the distribution or the vendor, each in the version you pick.' ;; + database) printf 'Every database listens on 127.0.0.1 with hardened authentication until you open it.' ;; + container) printf 'Docker or Podman, Portainer, or single-server Kubernetes with k3s. Published ports pass a firewall chain of their own.' ;; + backup) printf 'Encrypted daily backups with restic, database dumps before each run and a restore test every week.' ;; + monitoring) printf 'Metrics, logs and alerts with Prometheus, Grafana, Loki and Alloy, or Netdata on its own.' ;; + network) printf 'A WireGuard VPN for the admin interfaces, a validating DNS resolver and a time server.' ;; + mail) printf 'The server sends its own mail through a relay, or runs a mail server for your domains with webmail.' ;; + apps) printf 'Self-hosted apps as Docker Compose stacks behind the web server, each on its own host name.' ;; + *) printf 'The modules in modules/%s.' "${group}" ;; + esac + return +} + +scene_group() { + local group=$1 name option default _ count noun html text + local -a names=() + for name in "${MODULES[@]}"; do + [[ ${M_GROUP[${name}]} != "${group}" ]] || names+=("${name}") + done + count=${#names[@]} + scene_open "group-${group}" "modules/${group}" roll "$((2 + (count + 3) / 4))" + heading "group-${group}" "${group}" modules/ + noun=modules + if ((count == 1)); then + noun=module + fi + printf '

      %s %s

      \n' "${count}" "${noun}" + stage_open + printf '
        \n' + for name in "${names[@]}"; do + inline text "${M_DESC[${name}]}" + printf '
      • \n%s\n%s\n' "${name}" "${text}" + if [[ -n ${M_CONFLICTS[${name}]} ]]; then + esc text "${M_CONFLICTS[${name}]// /, }" + printf 'Instead of %s\n' "${text}" + fi + if [[ -n ${M_OPTIONS[${name}]} ]]; then + printf '' + while IFS='|' read -r option default _; do + [[ -n ${option} ]] || continue + text="LSS_${name}_${option}" + text=${text//-/_} + esc html "${default}" + printf '%s=%s ' "${text^^}" "${html}" + done <<<"${M_OPTIONS[${name}]}" + printf '\n' + fi + printf '
        • \n' + done + list_close ul + stage_close + scene_close "$(group_caption "${group}")" + return +} + +rule_row() { + local first=$1 second=$2 third=$3 class=${4:-} + printf '%s%s%s\n' "${class:+ ${class}}" "${first}" "${second}" "${third}" + return +} + +scene_security() { + scene_open security "Security model" steps 3 + heading security "Closed by default" + stage_open + cat <<'EOF' + + + + +EOF + rule_row 22/tcp allow "ssh-hardening: keys only, no root, no passwords" + rule_row "80/tcp 443/tcp" allow "nginx: HTTPS only, TLS 1.2 and 1.3" + rule_row 8090/tcp 127.0.0.1 "admin port of the web server, through an SSH tunnel or WireGuard" + rule_row 3306/tcp 127.0.0.1 "mariadb until LSS_MARIADB_ACCESS opens it" + rule_row "everything else" drop "firewall, with a timer that turns it off again if SSH stops answering" deny + printf '\n
        Inbound rules of a web server with the profile webhosting
        PortRuleWhy
        \n' + cat <<'EOF' +

        Modules never open ports themselves; they ask lss, which records the rule per module and closes it +when the module goes. The kernel is locked down, AppArmor or SELinux enforces, auditd records changes to accounts, +sudo and the network, and AIDE checks the files every day. The settings file is parsed and never run, and secrets +are files only root can read.

        +EOF + stage_close + scene_close "Inbound traffic stays closed except SSH and the ports of installed modules. Databases and admin +interfaces listen on 127.0.0.1 or the WireGuard network." + return +} + +scene_guard() { + local time threshold max_age + option_default time guard time + option_default threshold guard login_threshold + option_default max_age guard backup_max_age + [[ ${time} =~ ^[0-9:]+$ ]] || fail "guard: the default time '${time}' is not HH:MM." + scene_open guard "Guard" steps 3 + heading guard "Every morning at ${time}" + stage_open + printf '
        # systemctl cat lss-guard.timer\n[Timer]\nOnCalendar=*-*-* %s:00\nRandomizedDelaySec=10min
        \n' \ + "${time}" + printf '
          \n' + # shellcheck disable=SC2016 # backticks mark code + log_line verify 'every installed module, `lss verify`' ok + log_line repair 'nginx: a managed file was changed outside lss, configured again' + log_line report '3 security updates pending, reboot needed' + log_line report "71 failed SSH logins in 24 hours (more than ${threshold}), most from 203.0.113.0/24" deny + log_line report "last backup 6 hours ago (limit ${max_age} hours), restore test passed" + log_line sent 'webhook https://ntfy.sh/your-topic' + list_close ol + stage_close + scene_close "The guard module checks the server every day, repairs modules that drifted, and sends what +it found to a webhook or by e-mail. Failed services, full disks, vulnerable packages and container images are in the +report too." + return +} + +scene_install() { + scene_open install "Verified install" steps 3 + heading install "Verified before it runs" + stage_open + printf '
            \n' + log_line '$' 'gh release download -R VectoDE/Linux-Server-Setup-Script --pattern bootstrap.sh' cmdline + log_line '$' "gh attestation verify bootstrap.sh --repo VectoDE/Linux-Server-Setup-Script --cert-identity ${REPO_URL}/.github/workflows/release.yml@refs/heads/main" cmdline + log_line '$' 'sudo bash bootstrap.sh' cmdline + log_line OK 'SHA-256 of the release archive matches SHA256SUMS' ok + log_line OK 'attestation: built by release.yml from refs/heads/main on a GitHub-hosted runner' ok + log_line OK 'installed to /opt/lss/; /opt/lss/current points to it' ok + list_close ol + stage_close + scene_close "bootstrap.sh runs nothing it downloaded until the checksum matches and the Sigstore build +attestation proves the release workflow of this repository built it. lss update takes the same path, and +--rollback switches back." + return +} + +scene_cli() { + scene_open cli "Commands" roll 3 + heading cli "lss --help" + stage_open + local text + esc text "$(help_text)" + printf '
            %s
            \n' "${text}" + stage_close + scene_close "Settings are KEY=value lines in /etc/lss/lss.conf, named +LSS_<MODULE>_<OPTION>. --dry-run shows what a command would do." + return +} + +scene_menu() { + local -a items=() + local item tag text prompt + mapfile -t items < <(menu_items) + scene_open menu "Menu" switch "${#items[@]}" + heading menu "Or the menu" + stage_open + esc prompt "$(menu_prompt)" + esc text "${LSS_SITE_VERSION}" + printf '
            \n

            lss %s

            \n

            %s

            \n' "${text}" "${prompt}" + printf '
              \n' + for item in "${items[@]}"; do + esc tag "${item%%|*}" + esc text "${item#*|}" + printf '
            • %s%s
              • \n' "${tag}" "${text}" + done + printf '
            \n\n
            \n' + stage_close + scene_close "Without a command, sudo lss opens this menu. Choosing modules there runs the same install +as the command line." + return +} + +scene_systems() { + local distribution releases tested setup ram disk duration arch + scene_open systems "Systems" still 2 + heading systems "Where it runs" + stage_open + printf '\n\n' + printf '\n\n' + while IFS='|' read -r distribution releases tested; do + inline distribution "${distribution}" + inline releases "${releases}" + inline tested "${tested}" + printf '\n' "${distribution}" "${releases}" "${tested}" + done < <(systems_rows system) + inline arch "$(systems_rows arch)" + printf '\n
            Supported systems
            DistributionReleasesTested in CI
            %s%s%s
            \n

            %s

            \n' "${arch}" + printf '\n\n' + printf '\n\n' + while IFS='|' read -r setup ram disk duration; do + inline setup "${setup}" + inline ram "${ram}" + inline disk "${disk}" + inline duration "${duration}" + printf '\n' "${setup}" "${ram}" "${disk}" "${duration}" + done < <(systems_rows requirement) + printf '\n
            System requirements
            SetupRAMFree diskInstall time
            %s%s%s%s
            \n' + stage_close + scene_close "One CPU core is enough. The figures are the largest the integration tests measured on any tested +system; the README has them for every module." + return +} + +help_link() { + local path=$1 name=$2 what=$3 + printf '
          1. %s %s
            2. \n' "${REPO_URL}" "${path}" "${name}" "${what}" + return +} + +scene_help() { + scene_open help "Help" still 1 + heading help "Help" + stage_open + cat <<'EOF' +

            lss info guard

            +

            On the server, lss info MODULE shows what a module does, what it needs, its settings and +their defaults.

            +
              +EOF + help_link "#readme" "README" "installation, modules, profiles and settings" + help_link "blob/main/docs/troubleshooting.md" "Troubleshooting" "locked out, failed modules, common messages" + help_link "blob/main/docs/hardening.md" "Hardening guide" "what the security modules change, CIS mapping" + help_link "blob/main/docs/assurance.md" "Assurance case" "threat model and trust boundaries" + help_link "blob/main/docs/module-guide.md" "Writing a module" "the module format these pages are built from" + help_link "discussions" "Discussions" "questions and ideas" + help_link "issues/new/choose" "Report a bug" "with the bug template" + help_link "security/policy" "Security policy" "report vulnerabilities privately" + list_close ul + stage_close + scene_close "lss is free software under the MIT license, maintained in spare time." + return +} + +# --- page --------------------------------------------------------------------------------------------------------- + +# sha256_base64: the SHA-256 of stdin, base64 encoded as a CSP hash wants it. Coreutils only: the coverage run of the +# unit tests uses an image without openssl. +sha256_base64() { + local hex _name bytes='' index + read -r hex _name < <(sha256sum) + for ((index = 0; index < ${#hex}; index += 2)); do + bytes+="\x${hex:index:2}" + done + printf '%b' "${bytes}" | base64 -w 0 + return +} + +chapters() { + local index html + printf '
                \n' + for index in "${!SCENE_IDS[@]}"; do + esc html "${SCENE_TITLES[${index}]}" + printf '
              1. %s
                2. \n' "${SCENE_IDS[${index}]}" "${html}" + done + list_close ol + return +} + +build() { + local out=$1 body body_file css hash group + local file + for file in styles.css film.js favicon.svg robots.txt; do + [[ -f ${SITE_SRC}/${file} ]] || fail "${SITE_SRC}/${file} is missing." + done + load_modules + # The scenes run in this shell, not in a command substitution, so SCENE_IDS and SCENE_TITLES survive for the + # chapter list. + body_file=$(mktemp) + trap 'rm -f -- "${body_file}"' RETURN + { + scene_hero + scene_run + scene_profiles + for group in "${GROUPS_SORTED[@]}"; do + scene_group "${group}" + done + scene_security + scene_guard + scene_install + scene_cli + scene_menu + scene_systems + scene_help + } >"${body_file}" + body=$(<"${body_file}") + [[ $(grep -c '^
                + + + + + + + + + +lss: hardened Linux servers, one module at a time + + + + + + + +
                +lss + + +
                + +
                +${body} +
                +
                +

                lss ${LSS_SITE_VERSION}, MIT license. Source on GitHub.

                +

                This page is built from the module files of the repository on every deploy. It loads nothing from other servers +and sets no cookies.

                +
                + + + +EOF + } >"${out}/index.html" + cp "${SITE_SRC}/film.js" "${SITE_SRC}/favicon.svg" "${SITE_SRC}/robots.txt" "${out}/" + printf 'build-site: %s/index.html with %s scenes and %s modules\n' "${out}" "${#SCENE_IDS[@]}" "${#MODULES[@]}" + return +} + +case ${1:-} in +--check) check_readme ;; +-h | --help) sed -n '7,9p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,3\}//' ;; +-*) fail "unknown option '$1'." ;; +*) + check_readme + build "${1:-_site}" + ;; +esac diff --git a/site/favicon.svg b/site/favicon.svg new file mode 100644 index 0000000..695377c --- /dev/null +++ b/site/favicon.svg @@ -0,0 +1,11 @@ + + + + + + + diff --git a/site/film.js b/site/film.js new file mode 100644 index 0000000..b89a4db --- /dev/null +++ b/site/film.js @@ -0,0 +1,571 @@ +// SPDX-FileCopyrightText: 2025-2026 VectoDE +// +// SPDX-License-Identifier: MIT + +// Plays the film. Scrolling through a scene moves its progress from 0 to 1, and the progress decides which lines are +// shown (steps), how far the stage has rolled (roll), which item is current (switch) and how far the opening has +// stepped back (hero). Behind the text a field of packets drifts across the screen and closes into a shield while the +// module groups pass. Every word is in the page from the start; this script only moves and marks it. With reduced +// motion, without scripting or on a short screen the stylesheet shows the scenes as a still sequence, and the script +// only keeps the scene counter up to date. +"use strict"; + +(() => { + const film = globalThis.matchMedia( + "(prefers-reduced-motion: no-preference) and (scripting: enabled) and (height >= 30rem)", + ); + const dark = globalThis.matchMedia("(prefers-color-scheme: dark)"); + const counter = document.getElementById("tc-n"); + const title = document.getElementById("tc-title"); + const bar = document.querySelector(".bar"); + const scenes = Array.from(document.querySelectorAll(".scene"), (element) => ({ + element, + kind: element.dataset.kind, + // A scene of one screen (l1) is not played; it scrolls past like a page. + played: !element.classList.contains("l1"), + win: element.querySelector(".win"), + stage: element.querySelector(".stage"), + cap: element.querySelector(".cap"), + steps: Array.from(element.querySelectorAll(".s")), + items: Array.from(element.querySelectorAll(".m")), + lists: Array.from(element.querySelectorAll("[data-switch]"), (list) => Array.from(list.children)), + shift: -1, + split: false, + vars: "", + })); + const groups = scenes.filter((scene) => scene.element.id.startsWith("group-")); + const marks = { + start: document.getElementById("run"), + end: groups.length > 0 ? groups.at(-1).element : null, + guard: document.getElementById("guard"), + }; + // What the field needs from the page, written by render() on scroll and read by the field on every frame. + const state = { condense: 0, fade: 1, scan: -1, ghost: "", drift: 0 }; + let queued = false; + let shown = -1; + + const clamp = (value) => Math.min(1, Math.max(0, value)); + const easeOut = (value) => 1 - (1 - value) ** 3; + + // Bottom edge of an element, measured from the top of the stage, which is what a roll has to bring into view. + const bottomIn = (stage, element) => + element.getBoundingClientRect().bottom - stage.getBoundingClientRect().top; + + function roll(scene, shift) { + const value = Math.round(Math.max(0, shift)); + if (value !== scene.shift) { + scene.shift = value; + scene.stage.style.transform = value ? `translate3d(0, ${-value}px, 0)` : ""; + } + } + + // Lines appear one by one over the first 85 % of the scene, the newest is marked, and the stage rolls like a + // terminal once they no longer fit. + function playSteps(scene, progress) { + const count = scene.steps.length; + const visible = Math.max(1, Math.min(count, Math.ceil((progress / 0.85) * count))); + for (const [index, step] of scene.steps.entries()) { + step.classList.toggle("on", index < visible); + step.classList.toggle("now", index === visible - 1 && progress < 1); + } + roll(scene, bottomIn(scene.stage, scene.steps[visible - 1]) - scene.win.clientHeight); + } + + function playRoll(scene, progress) { + const count = scene.items.length; + const current = Math.round(progress * (count - 1)); + for (const [index, item] of scene.items.entries()) { + item.classList.toggle("cur", index === current); + } + roll(scene, progress * (scene.stage.scrollHeight - scene.win.clientHeight)); + } + + // One item per equal part of the scene; within its part, a tall item rolls to its end. + function playSwitch(scene, progress) { + const count = scene.lists[0].length; + const current = Math.min(count - 1, Math.floor(progress * count)); + for (const list of scene.lists) { + for (const [index, item] of list.entries()) { + item.classList.toggle("on", index === current); + } + } + const active = scene.lists.at(-1)[current]; + const local = clamp(progress * count - current); + roll(scene, local * (bottomIn(scene.stage, active) - scene.win.clientHeight)); + } + + function play(scene, progress) { + if (scene.kind === "hero") { + return; + } + if (scene.kind === "steps" && scene.steps.length > 0) { + playSteps(scene, progress); + } else if (scene.kind === "roll" && scene.items.length > 0) { + playRoll(scene, progress); + } else if (scene.kind === "switch" && scene.lists.length > 0) { + playSwitch(scene, progress); + } else { + roll(scene, progress * (scene.stage.scrollHeight - scene.win.clientHeight)); + } + } + + // The words of a caption, each in a span of its own with its place in the caption (--i, 0 to 1). Only text nodes + // are split, so links and code stay what they are. + function splitCaption(scene) { + scene.split = true; + if (!scene.cap || scene.kind === "hero") { + return; + } + const walker = document.createTreeWalker(scene.cap, NodeFilter.SHOW_TEXT); + const texts = []; + while (walker.nextNode()) { + texts.push(walker.currentNode); + } + const words = []; + for (const text of texts) { + const part = document.createDocumentFragment(); + for (const piece of text.data.split(/(\s+)/)) { + if (piece.trim() === "") { + part.append(piece); + } else { + const word = document.createElement("span"); + word.className = "wd"; + word.textContent = piece; + words.push(word); + part.append(word); + } + } + text.replaceWith(part); + } + for (const [index, word] of words.entries()) { + word.style.setProperty("--i", (index / Math.max(1, words.length - 1)).toFixed(3)); + } + } + + // --p (progress of a played scene) and --r (how far the scene has come in, for its caption) are only set while the + // scene is on the screen. Without them the stylesheet shows everything as it is. + function setVars(scene, progress, arrival) { + const value = `${progress.toFixed(3)} ${arrival.toFixed(3)}`; + if (value === scene.vars) { + return; + } + scene.vars = value; + scene.element.style.setProperty("--p", progress.toFixed(3)); + scene.element.style.setProperty("--r", arrival.toFixed(3)); + } + + function clearVars(scene) { + if (scene.vars !== "") { + scene.vars = ""; + scene.element.style.removeProperty("--p"); + scene.element.style.removeProperty("--r"); + } + } + + function still() { + for (const scene of scenes) { + roll(scene, 0); + clearVars(scene); + } + } + + function updateCounter(index) { + if (index === shown) { + return; + } + shown = index; + counter.textContent = String(index + 1).padStart(2, "0"); + title.textContent = scenes[index].element.dataset.title; + } + + function updateScene(scene, box, height) { + if (!film.matches || box.bottom <= 0 || box.top >= height) { + clearVars(scene); + return; + } + if (!scene.split) { + splitCaption(scene); + } + const run = box.height - height; + const progress = scene.played && run > 0 ? clamp(-box.top / run) : 0; + if (scene.played && run > 0) { + play(scene, progress); + } + setVars(scene, progress, clamp((height - box.top) / (1.6 * height))); + } + + // The shield closes from the moment the first run is half up the screen to the end of the last module group; the + // guard sweeps a scan line over it; after the guard the field fades out. + function updateField(height, current) { + if (marks.start && marks.end) { + const start = marks.start.getBoundingClientRect().top; + const span = marks.end.getBoundingClientRect().bottom - start - height / 2; + state.condense = clamp((height / 2 - start) / span); + } + if (marks.guard) { + const box = marks.guard.getBoundingClientRect(); + state.fade = clamp(box.bottom / height); + const run = box.height - height; + state.scan = box.top <= 0 && box.bottom >= height && run > 0 ? clamp(-box.top / run) : -1; + } + state.ghost = scenes[current].element.dataset.title; + state.drift = globalThis.scrollY; + } + + // All boxes are measured first and only then written to, so a frame lays the page out once (the rolls of the + // one or two scenes on the screen measure their own stage, which the writes before them leave in place). + function render() { + queued = false; + const height = globalThis.innerHeight; + const total = document.documentElement.scrollHeight - height; + const boxes = scenes.map((scene) => scene.element.getBoundingClientRect()); + let current = 0; + for (const [index, box] of boxes.entries()) { + if (box.top <= height / 2) { + current = index; + } + } + updateField(height, current); + for (const [index, scene] of scenes.entries()) { + updateScene(scene, boxes[index], height); + } + updateCounter(current); + field.wake(); + bar.style.transform = `scaleX(${total > 0 ? clamp(globalThis.scrollY / total) : 0})`; + } + + function queue() { + if (!queued) { + queued = true; + globalThis.requestAnimationFrame(render); + } + } + + // The field. Each packet has a place on the screen it drifts from and a place in the shield it closes into; the + // order in which they arrive is random, so the shape fills in rather than wiping across. + const field = (() => { + const canvas = document.querySelector(".field"); + const context = canvas ? canvas.getContext("2d", { alpha: true }) : null; + const colours = { ink: "", muted: "", mark: "", mono: "" }; + let packets = null; + let width = 0; + let height = 0; + let running = false; + let started = false; + let smooth = 0; + let blank = false; + + function readColours() { + const style = getComputedStyle(document.documentElement); + for (const name of ["ink", "muted", "mark", "mono"]) { + colours[name] = style.getPropertyValue(`--${name}`).trim(); + } + } + + // Points of a shield with "lss" cut out of it, from a small drawing that is read once. The grid is as fine as the + // number of packets allows, so that every point gets one and the letters stay readable. + function shieldPoints(count) { + const sketch = document.createElement("canvas"); + sketch.width = 200; + sketch.height = 240; + const pen = sketch.getContext("2d", { willReadFrequently: true }); + pen.beginPath(); + pen.moveTo(100, 4); + pen.lineTo(196, 34); + pen.lineTo(196, 112); + pen.quadraticCurveTo(196, 196, 100, 236); + pen.quadraticCurveTo(4, 196, 4, 112); + pen.lineTo(4, 34); + pen.closePath(); + pen.fill(); + pen.globalCompositeOperation = "destination-out"; + pen.font = `800 76px ${colours.mono}`; + pen.textAlign = "center"; + pen.fillText("lss", 100, 140); + const pixels = pen.getImageData(0, 0, 200, 240).data; + let area = 0; + for (let index = 3; index < pixels.length; index += 4) { + area += pixels[index] > 128 ? 1 : 0; + } + return sample(pixels, Math.max(2, Math.sqrt(area / count) * 1.02)); + } + + function sample(pixels, step) { + const points = []; + for (let y = step / 2; y < 240; y += step) { + for (let x = step / 2; x < 200; x += step) { + if (pixels[(Math.floor(y) * 200 + Math.floor(x)) * 4 + 3] > 128) { + points.push((x - 100) / 240, (y - 120) / 240); + } + } + } + return points; + } + + // The scatter of the packets only has to look random, and the same on every visit: a small seeded generator + // (mulberry32), nothing that needs to be unpredictable. + let seed = 0x6c7373; + function scatter() { + seed = (seed + 0x6d2b79f5) >>> 0; + let value = Math.imul(seed ^ (seed >>> 15), 1 | seed); + value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value; + return ((value ^ (value >>> 14)) >>> 0) / 4294967296; + } + + function makePackets() { + seed = 0x6c7373; + const count = Math.round(Math.min(2200, Math.max(500, (width * height) / 420))); + const points = shieldPoints(count); + const total = points.length / 2; + const order = Array.from({ length: total }, (_, index) => index); + for (let index = total - 1; index > 0; index -= 1) { + const other = Math.floor(scatter() * (index + 1)); + [order[index], order[other]] = [order[other], order[index]]; + } + packets = Array.from({ length: count }, (_, index) => { + const point = order[index % total]; + const spread = index < total ? 0 : 0.006; + return { + hx: scatter(), + hy: scatter(), + speed: 0.00001 + scatter() * 0.00003, + depth: 0.3 + scatter() * 0.7, + tx: points[point * 2] + (scatter() - 0.5) * spread, + ty: points[point * 2 + 1] + (scatter() - 0.5) * spread, + delay: scatter(), + }; + }); + } + + function resize() { + const ratio = Math.min(1.5, globalThis.devicePixelRatio || 1); + width = globalThis.innerWidth; + height = globalThis.innerHeight; + canvas.width = Math.round(width * ratio); + canvas.height = Math.round(height * ratio); + context.setTransform(ratio, 0, 0, ratio, 0, 0); + } + + function drawGhost() { + if (shown <= 0) { + return; + } + const size = Math.round(Math.min(height * 0.3, width * 0.22)); + context.font = `800 ${size}px ${colours.mono}`; + context.fillStyle = colours.ink; + context.globalAlpha = 0.05; + context.fillText(state.ghost, -state.drift * 0.08 % width, height * 0.62); + } + + // One frame: packets drift on their own line until their turn comes, then travel into the shield. + function draw(time) { + context.clearRect(0, 0, width, height); + context.globalAlpha = 1; + drawGhost(); + smooth += (state.condense - smooth) * 0.08; + const size = Math.min(width * (width >= 900 ? 0.42 : 0.78), height * 0.62) * 1.2; + const centreX = width >= 900 ? width * 0.7 : width / 2; + const centreY = height * 0.54; + const scanY = state.scan >= 0 ? centreY + (state.scan - 0.5) * size : -1e4; + const buckets = [[], [], []]; + for (const packet of packets) { + const turn = easeOut(clamp((smooth - packet.delay * 0.6) / 0.4)); + const freeX = ((packet.hx + time * packet.speed) % 1) * width; + const freeY = packet.hy * height - state.drift * 0.04 * packet.depth; + const y = ((freeY % height) + height) % height; + const x = freeX + (centreX + packet.tx * size - freeX) * turn; + const ty = y + (centreY + packet.ty * size - y) * turn; + let bucket = turn >= 1 ? 1 : 0; + if ((turn > 0 && turn < 1) || Math.abs(ty - scanY) < 6) { + bucket = 2; + } + buckets[bucket].push(x, ty); + } + // On a narrow screen the shield sits behind the text, so it is drawn fainter there. + const level = state.fade * (width >= 900 ? 1 : 0.5); + paint(buckets[0], colours.muted, 0.34 * level); + paint(buckets[1], colours.ink, 0.42 * level); + paint(buckets[2], colours.mark, 0.7 * level); + if (state.scan >= 0) { + context.fillStyle = colours.mark; + context.globalAlpha = level; + context.fillRect(centreX - size * 0.45, scanY - 1, size * 0.9, 2); + } + } + + function paint(points, colour, alpha) { + context.fillStyle = colour; + context.globalAlpha = alpha; + for (let index = 0; index < points.length; index += 2) { + context.fillRect(points[index], points[index + 1], 2, 2); + } + } + + function frame(time) { + if (!running) { + return; + } + if (state.fade <= 0) { + // Past the guard: one empty frame, then nothing until the field comes back into play. + if (!blank) { + context.clearRect(0, 0, width, height); + blank = true; + } + running = false; + return; + } + blank = false; + draw(time); + globalThis.requestAnimationFrame(frame); + } + + function wake() { + if (!started || running || document.hidden || !film.matches || state.fade <= 0) { + return; + } + running = true; + globalThis.requestAnimationFrame(frame); + } + + function sleep() { + running = false; + } + + function start() { + if (!context || started || !film.matches) { + return; + } + started = true; + readColours(); + resize(); + makePackets(); + wake(); + } + + function refit() { + if (started) { + resize(); + } + } + + function recolour() { + if (started) { + readColours(); + } + } + + return { start, wake, sleep, refit, recolour }; + })(); + + // The numbers of the opening count up once, from 0 to what the repository holds. + function countUp() { + const numbers = Array.from(document.querySelectorAll("dd[data-count]"), (element) => ({ + element, + target: Number(element.dataset.count), + })); + // Each number keeps the width of its final value, so counting does not move the labels around it. + for (const number of numbers) { + number.element.style.minWidth = `${String(number.target).length}ch`; + } + const begin = performance.now(); + const tick = (time) => { + const done = clamp((time - begin) / 1400); + for (const number of numbers) { + number.element.textContent = String(Math.round(easeOut(done) * number.target)); + } + if (done < 1) { + globalThis.requestAnimationFrame(tick); + } + }; + globalThis.requestAnimationFrame(tick); + } + + // Where the browser cannot drive the heading masks by scroll, they rise once their heading comes into view. The + // stylesheet only lowers them once this script has marked the page (fx), so a page whose script did not load + // keeps its headings in place. + function watchHeadings() { + if (globalThis.CSS?.supports("animation-timeline: view()") || !("IntersectionObserver" in globalThis)) { + return; + } + document.documentElement.classList.add("fx"); + const observer = new IntersectionObserver( + (entries) => { + for (const entry of entries) { + if (entry.isIntersecting) { + entry.target.classList.add("seen"); + observer.unobserve(entry.target); + } + } + }, + { threshold: 0.2 }, + ); + for (const heading of document.querySelectorAll("h2")) { + observer.observe(heading); + } + } + + // The chapter list closes when a chapter is chosen, and with Escape, which returns focus to its button. + const chapters = document.querySelector(".hud-nav details"); + chapters.addEventListener("click", (event) => { + if (event.target.closest("a")) { + chapters.open = false; + } + }); + document.addEventListener("keydown", (event) => { + if (event.key === "Escape" && chapters.open) { + chapters.open = false; + chapters.querySelector("summary").focus(); + } + }); + + film.addEventListener("change", () => { + if (film.matches) { + field.start(); + } else { + field.sleep(); + still(); + } + queue(); + }); + dark.addEventListener("change", field.recolour); + document.addEventListener("visibilitychange", () => { + if (document.hidden) { + field.sleep(); + } else { + field.wake(); + } + }); + globalThis.addEventListener("scroll", queue, { passive: true }); + globalThis.addEventListener( + "resize", + () => { + field.refit(); + queue(); + }, + { passive: true }, + ); + + // The first frame waits for the page to load: by then the browser has laid it out, so measuring the scenes costs + // nothing, and the page is complete without this frame anyway. The field and the counters start after it. + function begin() { + watchHeadings(); + queue(); + if (film.matches) { + countUp(); + const later = globalThis.requestIdleCallback?.bind(globalThis) ?? ((callback) => globalThis.setTimeout(callback, 600)); + later( + () => { + field.start(); + queue(); + }, + { timeout: 1500 }, + ); + } + } + + if (document.readyState === "complete") { + begin(); + } else { + globalThis.addEventListener("load", begin, { once: true }); + } +})(); diff --git a/site/lighthouserc.json b/site/lighthouserc.json new file mode 100644 index 0000000..b40381b --- /dev/null +++ b/site/lighthouserc.json @@ -0,0 +1,16 @@ +{ + "ci": { + "collect": { + "staticDistDir": "./_site", + "numberOfRuns": 3 + }, + "assert": { + "assertions": { + "categories:performance": ["error", { "minScore": 1, "aggregationMethod": "median-run" }], + "categories:accessibility": ["error", { "minScore": 1, "aggregationMethod": "median-run" }], + "categories:best-practices": ["error", { "minScore": 1, "aggregationMethod": "median-run" }], + "categories:seo": ["error", { "minScore": 1, "aggregationMethod": "median-run" }] + } + } + } +} diff --git a/site/robots.txt b/site/robots.txt new file mode 100644 index 0000000..e8f841d --- /dev/null +++ b/site/robots.txt @@ -0,0 +1,6 @@ +# SPDX-FileCopyrightText: 2025-2026 VectoDE +# +# SPDX-License-Identifier: MIT + +User-agent: * +Allow: / diff --git a/site/styles.css b/site/styles.css new file mode 100644 index 0000000..0d2baf4 --- /dev/null +++ b/site/styles.css @@ -0,0 +1,920 @@ +/* + * SPDX-FileCopyrightText: 2025-2026 VectoDE + * + * SPDX-License-Identifier: MIT + */ + +/* + * The page is a sequence of full-screen frames, readable as it is. With motion allowed, scripting on and a screen tall + * enough, every scene becomes longer than the screen, its frame sticks, and film.js plays it while it scrolls past + * (the block at the end). Colour code: yellow marks what lss is doing right now, red what it refuses or what failed. + * Fonts are the system's own; the page loads nothing from other servers. + */ + +:root { + color-scheme: light dark; + --bg: #f3f5f8; + --ink: #0f2747; + --muted: #475b7a; + --line: #c3cddb; + --mark: #ffd84d; + --on-mark: #0f2747; + --deny: #b3261e; + --hud: 3rem; + --gut: clamp(1rem, 4vw, 3.5rem); + --sans: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans", Ubuntu, Cantarell, "Helvetica Neue", Arial, sans-serif; + --mono: ui-monospace, "Cascadia Mono", "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", "Liberation Mono", monospace; +} + +@media (prefers-color-scheme: dark) { + :root { + --bg: #0b1a30; + --ink: #e6ecf5; + --muted: #9fb1ca; + --line: #2a4266; + --mark: #f5c842; + --on-mark: #0b1a30; + --deny: #ff8f85; + } +} + +*, +*::before, +*::after { + box-sizing: border-box; +} + +html { + text-size-adjust: 100%; +} + +body { + margin: 0; + background: var(--bg); + color: var(--ink); + font: 400 1.0625rem/1.55 var(--sans); + overflow-wrap: break-word; +} + +h1, +h2, +h3, +p, +pre { + margin: 0; +} + +a { + color: inherit; + text-decoration-thickness: 1px; + text-underline-offset: 0.2em; +} + +a:hover { + text-decoration-thickness: 2px; +} + +:focus-visible { + outline: 3px solid var(--ink); + outline-offset: 2px; +} + +a:focus-visible, +summary:focus-visible { + background: var(--mark); + color: var(--on-mark); +} + +code { + font-family: var(--mono); + font-size: 0.92em; +} + +::selection { + background: var(--mark); + color: var(--on-mark); +} + +.skip { + position: absolute; + top: -10rem; + left: var(--gut); + z-index: 3; + padding: 0.6rem 1ch; + background: var(--mark); + color: var(--on-mark); + font-family: var(--mono); +} + +.skip:focus { + top: 0.5rem; +} + +/* Head-up display: the chapters and the scene that is playing. */ + +.hud { + position: fixed; + inset: 0 0 auto; + z-index: 2; + display: flex; + gap: 2.5ch; + align-items: center; + height: var(--hud); + /* Lines up with the frames, which stop growing at 96rem. */ + padding: 0 max(var(--gut), calc((100% - 96rem) / 2 + var(--gut))); + border-bottom: 1px solid var(--line); + background: var(--bg); + font: 500 0.875rem/1 var(--mono); +} + +.hud-mark { + padding: 0.6rem 0; + font-size: 1.125rem; + font-weight: 800; + letter-spacing: -0.04em; + text-decoration: none; +} + +.hud-nav { + position: relative; +} + +.hud-nav summary { + padding: 0.85rem 0; + cursor: pointer; + list-style: none; +} + +.hud-nav summary::-webkit-details-marker { + display: none; +} + +.hud-nav summary::after { + content: " +"; + color: var(--muted); +} + +.hud-nav details[open] summary::after { + content: " \2212"; +} + +.hud-nav ol { + position: absolute; + top: calc(100% + 0.25rem); + left: 0; + width: min(20rem, calc(100vw - 2 * var(--gut))); + max-height: calc(100svh - var(--hud) - 1.5rem); + margin: 0; + padding: 0.5rem 0; + overflow-y: auto; + border: 2px solid var(--ink); + background: var(--bg); + list-style: none; + counter-reset: chapter; +} + +.hud-nav li { + counter-increment: chapter; +} + +.hud-nav a { + display: flex; + gap: 1.5ch; + padding: 0.5rem 1rem; + text-decoration: none; +} + +.hud-nav a::before { + content: counter(chapter, decimal-leading-zero); + color: var(--muted); +} + +.hud-nav a:focus-visible::before { + color: inherit; +} + +.hud-tc { + display: flex; + gap: 1ch; + min-width: 0; + margin-left: auto; + white-space: nowrap; +} + +.hud-of { + margin-left: -1ch; + color: var(--muted); +} + +#tc-title { + overflow: hidden; + text-overflow: ellipsis; +} + +.bar { + position: fixed; + right: 0; + bottom: 0; + left: 0; + z-index: 2; + height: 4px; + background: var(--mark); + transform: scaleX(0); + transform-origin: 0 50%; +} + +/* A frame: the splice line with the scene number, the title, the stage and the caption. */ + +/* Scenes below the first are laid out when they come near the screen, which keeps the first layout small. */ +.scene + .scene { + content-visibility: auto; + contain-intrinsic-size: auto 100svh; +} + +.frame { + display: flex; + flex-direction: column; + gap: 1rem; + max-width: 96rem; + min-height: 100svh; + margin: 0 auto; + padding: calc(var(--hud) + 1.25rem) var(--gut) 1.75rem; +} + +.splice { + display: flex; + gap: 2ch; + padding-top: 0.6rem; + border-top: 2px solid var(--ink); + color: var(--muted); + font: 500 0.8125rem/1 var(--mono); +} + +.splice span:first-child { + color: var(--ink); + font-weight: 700; +} + +h2 { + font: 700 clamp(1.75rem, 0.9rem + 5vw, 6rem)/1.02 var(--mono); + letter-spacing: -0.045em; + text-wrap: balance; + overflow-wrap: anywhere; +} + +h2 .path { + color: var(--muted); + font-weight: 400; +} + +.meta { + color: var(--muted); + font: 500 0.9375rem/1 var(--mono); +} + +.win { + position: relative; + flex: 1 1 auto; + min-height: 0; +} + +.stage { + position: relative; +} + +.cap { + max-width: 52ch; + margin: auto auto 0; + padding-top: 1rem; + font-size: clamp(1rem, 0.9rem + 0.45vw, 1.25rem); + font-weight: 500; + line-height: 1.45; + text-align: center; + text-wrap: balance; +} + +.lead, +.note { + max-width: 62ch; + text-wrap: pretty; +} + +.lead { + margin-top: 1.25rem; + font-size: clamp(1.0625rem, 1rem + 0.4vw, 1.3125rem); +} + +.note { + margin-top: 1.5rem; +} + +/* Opening scene */ + +h1 { + display: flex; + flex-wrap: wrap; + gap: 0.5rem 2ch; + align-items: baseline; + margin-top: auto; +} + +.h1-word { + margin-left: -0.05em; + font: 800 clamp(6rem, 36vw, 22rem)/0.8 var(--mono); + letter-spacing: -0.07em; +} + +.h1-sub { + color: var(--muted); + font: 500 clamp(1rem, 0.8rem + 1vw, 1.5rem)/1.2 var(--mono); +} + +#top .win { + flex: 0 0 auto; +} + +#top .cap { + margin-top: 2rem; +} + +/* The command is sized so that its 43 characters fit one line from 352 px up; narrower screens wrap it. */ +.cmd { + width: fit-content; + max-width: 100%; + padding: 0.35em 0.6ch; + background: var(--mark); + color: var(--on-mark); + font: 600 clamp(0.75rem, 3.2vw, 1.75rem)/1.35 var(--mono); + overflow-wrap: anywhere; +} + +@media (width >= 22rem) { + .cmd { + white-space: nowrap; + } +} + +.t-hero { + display: inline-block; +} + +/* What the repository holds, counted on every build. The number comes first, its label below it. */ +.nums { + display: flex; + flex-wrap: wrap; + gap: 1rem 5ch; + margin: 1.75rem 0 0; + font-family: var(--mono); +} + +.nums div { + display: flex; + flex-direction: column-reverse; + gap: 0.35rem; +} + +.nums dt { + color: var(--muted); + font-size: 0.875rem; + line-height: 1.2; +} + +.nums dd { + margin: 0; + font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem); + font-weight: 700; + font-variant-numeric: tabular-nums; + line-height: 1; + letter-spacing: -0.04em; +} + +/* Every word of a heading sits in a mask of its own, so the film can raise it into view. */ +h2 .w { + display: inline-block; + padding-bottom: 0.08em; + overflow: hidden; + vertical-align: top; +} + +h2 .w > span { + display: inline-block; +} + +/* The field (film.js draws it with motion allowed): packets that close into a shield while the modules pass. */ +.field { + display: none; +} + +/* Logs in the format of lss: level, then the message */ + +.log { + max-width: 110ch; + margin: 0; + padding: 0; + font: 400 clamp(0.8125rem, 0.75rem + 0.35vw, 1.125rem)/1.6 var(--mono); + list-style: none; +} + +.log li { + display: grid; + grid-template-columns: 6ch minmax(0, 1fr); + column-gap: 1ch; + padding: 0 0.5ch; + overflow-wrap: anywhere; +} + +.lv { + color: var(--muted); +} + +.log .ok .lv { + color: var(--ink); + font-weight: 700; +} + +.log .cmdline { + margin-top: 0.35rem; + font-weight: 600; +} + +.log .deny, +.log .deny .lv { + color: var(--deny); + font-weight: 600; +} + +.log-head { + margin: 1.75rem 0 0.35rem; + color: var(--muted); + font: 600 0.9375rem/1.2 var(--sans); +} + +.report { + margin-top: 0.5rem; +} + +.report li { + grid-template-columns: 7ch minmax(0, 1fr); +} + +.unit { + margin-bottom: 1.5rem; + padding-left: 2ch; + border-left: 2px solid var(--ink); + font: 400 clamp(0.8125rem, 0.75rem + 0.35vw, 1.0625rem)/1.6 var(--mono); + white-space: pre-wrap; +} + +.u-c { + color: var(--muted); +} + +.help { + font: 400 clamp(0.75rem, 0.6rem + 0.45vw, 1rem)/1.5 var(--mono); + white-space: pre-wrap; + overflow-wrap: anywhere; +} + +/* Modules of a group */ + +.mods { + margin: 0; + padding: 0; + list-style: none; +} + +.m { + display: grid; + grid-template-columns: clamp(11rem, 24vw, 14rem) minmax(0, 1fr); + column-gap: 3ch; + padding: 0.9rem 0; + border-top: 1px solid var(--line); +} + +.m-name { + grid-row: span 3; + align-self: start; + justify-self: start; + font: 700 clamp(1rem, 0.9rem + 0.5vw, 1.375rem)/1.3 var(--mono); +} + +.m-desc { + max-width: 70ch; +} + +.m-alt { + color: var(--muted); + font-size: 0.9375rem; +} + +.m-opt { + color: var(--muted); + font: 400 0.8125rem/1.6 var(--mono); + overflow-wrap: anywhere; +} + +.m-opt code { + margin-right: 1.5ch; + font-size: 1em; +} + +/* Profiles: in the film one at a time, otherwise one after the other */ + +.sw-names { + display: none; +} + +.sw-items .o { + padding: 1rem 0; + border-top: 1px solid var(--line); +} + +.o h3 { + margin-bottom: 0.35rem; + font: 700 clamp(1.25rem, 1rem + 1.2vw, 2rem)/1.2 var(--mono); + letter-spacing: -0.02em; +} + +.o-desc { + max-width: 62ch; + margin-bottom: 0.5rem; +} + +.o-count { + margin-bottom: 0.35rem; + color: var(--muted); + font-size: 0.9375rem; +} + +.o-mods { + max-width: 92ch; + font: 400 clamp(0.8125rem, 0.75rem + 0.3vw, 1rem)/1.65 var(--mono); + word-spacing: 0.6ch; +} + +.o-mods span { + white-space: nowrap; +} + +/* The menu, drawn like whiptail draws it */ + +.tui { + max-width: 46rem; + padding-bottom: 1.25rem; + border: 2px solid var(--ink); + box-shadow: 0.6rem 0.6rem 0 var(--line); + font: 400 clamp(0.875rem, 0.8rem + 0.3vw, 1.0625rem)/1.4 var(--mono); +} + +.tui-title { + padding: 0.4rem 1ch; + background: var(--ink); + color: var(--bg); + font-weight: 700; + text-align: center; +} + +.tui-prompt { + margin: 1rem 2ch 0.75rem; +} + +.tui-items { + margin: 0 2ch; + padding: 0; + list-style: none; +} + +.tui-items li { + display: grid; + grid-template-columns: 8ch minmax(0, 1fr); + gap: 1ch; + padding: 0.3rem 1ch; +} + +.tui-tag { + font-weight: 700; +} + +.tui-buttons { + display: flex; + gap: 6ch; + justify-content: center; + margin-top: 1.25rem; +} + +/* Tables: firewall rules and systems */ + +table { + width: 100%; + max-width: 72rem; + border-collapse: collapse; +} + +caption { + padding-bottom: 0.6rem; + color: var(--muted); + font: 600 0.9375rem/1.3 var(--sans); + text-align: left; +} + +th, +td { + padding: 0.55rem 2ch 0.55rem 0; + border-top: 1px solid var(--line); + text-align: left; + vertical-align: top; + overflow-wrap: anywhere; +} + +th { + border-top: 0; + color: var(--muted); + font: 600 0.8125rem/1.2 var(--sans); +} + +.rules td:first-child, +.rules td:nth-child(2) { + font-family: var(--mono); +} + +.rules td:nth-child(2) { + font-weight: 700; + white-space: nowrap; +} + +.rules .deny td { + color: var(--deny); + font-weight: 600; +} + +.sys { + margin-bottom: 1.5rem; +} + +.sys + .note { + margin: -0.5rem 0 2rem; +} + +.sys td:first-child { + font-weight: 600; +} + +/* Help */ + +.links { + max-width: 60rem; + margin: 1.5rem 0 0; + padding: 0; + list-style: none; +} + +.links li { + padding: 0.45rem 0; + border-top: 1px solid var(--line); + color: var(--muted); +} + +.links a { + display: inline-block; + margin-right: 1.5ch; + padding: 0.2rem 0; + color: var(--ink); + font: 600 1.0625rem/1.4 var(--mono); +} + +.foot { + max-width: 96rem; + margin: 0 auto; + padding: 2.5rem var(--gut) 3.5rem; + border-top: 2px solid var(--ink); + color: var(--muted); + font-size: 0.9375rem; +} + +.foot p { + max-width: 70ch; + margin-bottom: 0.5rem; +} + +.foot a { + color: var(--ink); +} + +@media (width <= 40rem) { + .m { + grid-template-columns: minmax(0, 1fr); + } + + .m-name { + grid-row: auto; + } + + .hud { + gap: 1.5ch; + } +} + +/* The film. film.js uses the same media query. */ + +@media (prefers-reduced-motion: no-preference) and (scripting: enabled) and (height >= 30rem) { + .l2 { + height: 200svh; + } + + .l3 { + height: 300svh; + } + + .l4 { + height: 400svh; + } + + .l5 { + height: 500svh; + } + + .l6 { + height: 600svh; + } + + .field { + position: fixed; + inset: 0; + z-index: 0; + display: block; + width: 100%; + height: 100%; + pointer-events: none; + } + + main, + .foot { + position: relative; + z-index: 1; + } + + /* The opening steps back while the film starts. */ + #top h1 { + transform: translate3d(0, calc(var(--p, 0) * -14svh), 0) scale(calc(1 - var(--p, 0) * 0.22)); + transform-origin: 0 100%; + } + + /* + * Captions come in word by word while their scene arrives. film.js sets --r (0 to 1) only on a scene on the screen; + * everywhere else the words are fully there, so nothing is hidden from a reader that does not scroll. + */ + .cap .wd { + --a: clamp(0, (var(--r, 1) - var(--i) * 0.6) * 4, 1); + opacity: calc(0.12 + 0.88 * var(--a)); + filter: blur(calc((1 - var(--a)) * 3px)); + } + + /* A scene of one screen (l1) is not played: it scrolls past like a page. */ + .scene:not(.l1) .frame { + position: sticky; + top: 0; + height: 100svh; + min-height: 0; + overflow: hidden; + } + + .scene:not(.l1) .win { + overflow: hidden; + } + + .s { + opacity: 0; + } + + .s.on { + opacity: 1; + } + + .log .now, + .log .now .lv, + .m.cur .m-name, + .sw-names .on, + .tui-items .on { + background: var(--mark); + color: var(--on-mark); + } + + .m-name { + margin-left: -0.5ch; + padding: 0 0.5ch; + } + + .sw { + display: grid; + grid-template-columns: minmax(12ch, 18ch) minmax(0, 1fr); + column-gap: 4ch; + align-items: start; + } + + .sw-names { + display: block; + margin: 0; + padding: 0; + color: var(--muted); + font: 600 1rem/1 var(--mono); + list-style: none; + } + + .sw-names li { + padding: 0.55rem 0.75ch; + } + + .sw-items { + display: grid; + } + + .sw-items .o { + grid-area: 1 / 1; + padding-top: 0; + border-top: 0; + opacity: 0; + } + + .sw-items .o.on { + opacity: 1; + } + + /* 41 characters, typed once when the page opens */ + .t-hero { + animation: type 1.1s steps(41, end) 0.2s both; + } + + @keyframes type { + from { + clip-path: inset(0 100% 0 0); + } + + to { + clip-path: inset(0); + } + } + + @keyframes rise { + from { + transform: translate3d(0, 105%, 0); + } + } +} + +/* The words of a heading rise out of their masks as it scrolls in: driven by the scroll where the browser can. */ +@media (prefers-reduced-motion: no-preference) and (scripting: enabled) and (height >= 30rem) { + @supports (animation-timeline: view()) { + h2 .w > span { + animation: rise linear both; + animation-timeline: view(); + animation-range: entry 0% entry 90%; + } + + h2 .w:nth-child(2) > span { + animation-range: entry 8% entry 98%; + } + + h2 .w:nth-child(3) > span { + animation-range: entry 16% cover 30%; + } + + h2 .w:nth-child(n + 4) > span { + animation-range: entry 24% cover 34%; + } + } + + /* Elsewhere film.js marks the page (fx) and then each heading as seen when it comes into view. */ + @supports not (animation-timeline: view()) { + .fx h2 .w > span { + transform: translate3d(0, 105%, 0); + transition: transform 0.8s cubic-bezier(0.2, 0.7, 0.2, 1); + } + + .fx h2 .w:nth-child(2) > span { + transition-delay: 0.07s; + } + + .fx h2 .w:nth-child(3) > span { + transition-delay: 0.14s; + } + + .fx h2 .w:nth-child(n + 4) > span { + transition-delay: 0.21s; + } + + .fx h2.seen .w > span { + transform: none; + } + } +} + +@media (prefers-reduced-motion: no-preference) and (scripting: enabled) and (height >= 30rem) and (width <= 40rem) { + /* One column: the heading of each profile names it, the index would only push it down. */ + .sw { + grid-template-columns: minmax(0, 1fr); + } + + .sw-names { + display: none; + } +} diff --git a/tests/unit/site.bats b/tests/unit/site.bats new file mode 100644 index 0000000..5ad37d2 --- /dev/null +++ b/tests/unit/site.bats @@ -0,0 +1,126 @@ +#!/usr/bin/env bats +# SPDX-FileCopyrightText: 2025-2026 VectoDE +# +# SPDX-License-Identifier: MIT + +# The website generator (scripts/build-site.sh): everything on the page comes from the repository, the Content +# Security Policy allows exactly the inlined stylesheet, and the README tables have to match data/systems.conf. + +setup_file() { + bats_require_minimum_version 1.5.0 + REPO_ROOT=$(cd "${BATS_TEST_DIRNAME}/../.." && pwd) + export REPO_ROOT + "${REPO_ROOT}/scripts/build-site.sh" "${BATS_FILE_TMPDIR}/site" >/dev/null + export PAGE=${BATS_FILE_TMPDIR}/site/index.html +} + +# copy_repo: the files the generator reads, in a directory of their own, so a test can change them. +copy_repo() { + ROOT=${BATS_TEST_TMPDIR}/repo + mkdir -p "${ROOT}/lib" + cp -r "${REPO_ROOT}/scripts" "${REPO_ROOT}/site" "${REPO_ROOT}/modules" "${REPO_ROOT}/profiles" "${ROOT}/" + mkdir -p "${ROOT}/data" + cp "${REPO_ROOT}/data/systems.conf" "${ROOT}/data/" + cp "${REPO_ROOT}/lib/ui.sh" "${ROOT}/lib/" + cp "${REPO_ROOT}/lss" "${REPO_ROOT}/VERSION" "${REPO_ROOT}/README.md" "${ROOT}/" +} + +@test "the page has every module, group and profile of the repository" { + local file name group + for file in "${REPO_ROOT}"/modules/*/*.sh; do + name=$(basename "${file}" .sh) + group=$(basename "$(dirname "${file}")") + grep -qF "${name}" "${PAGE}" + grep -qF "id=\"group-${group}\"" "${PAGE}" + done + for file in "${REPO_ROOT}"/profiles/*.conf; do + grep -qF "

                $(basename "${file}" .conf)

                " "${PAGE}" + done +} + +@test "every scene is in the chapter list" { + local scenes chapters + scenes=$(grep -c '^
                /p' "${PAGE}" | grep -c '^
              2. /${scenes}" "${PAGE}" +} + +@test "the settings shown are the options of the modules with their defaults" { + grep -qF 'LSS_GUARD_TIME=07:00' "${PAGE}" + grep -qF 'LSS_KERNEL_HARDENING_BLOCK_USB_STORAGE=true' "${PAGE}" + grep -qF 'Instead of apache, caddy' "${PAGE}" + grep -qF '

                Every morning at 07:00

                ' "${PAGE}" +} + +@test "the help text comes from lss and the menu from lib/ui.sh" { + grep -qF 'install --profile NAME install a profile' "${PAGE}" + grep -qF "lss $(<"${REPO_ROOT}/VERSION"): modular, hardened Linux server setup" "${PAGE}" + grep -qF 'Install a profile (a ready-made set of modules)
                3. ' "${PAGE}" +} + +@test "the policy allows exactly the inlined stylesheet and the page loads nothing from elsewhere" { + local css hash page + command -v openssl >/dev/null || skip "openssl is missing, which checks the hash independently" + css=$(<"${REPO_ROOT}/site/styles.css") + hash=$(printf '%s' "${css}" | openssl dgst -sha256 -binary | openssl base64 -A) + page=$(<"${PAGE}") + [[ ${page} == *""* ]] + grep -qF "style-src 'sha256-${hash}'" "${PAGE}" + grep -qF "default-src 'none'; script-src 'self';" "${PAGE}" + [ "$(grep -c '' "${PAGE}" + run grep -E '(src|href)="(https?:)?//' "${PAGE}" + [ "${status}" -eq 0 ] + # Links to the repository are the only absolute URLs, and none of them is a resource the page loads. + run grep -E '<(script|link|img)[^>]+(src|href)="(https?:)?//' "${PAGE}" + [ "${status}" -eq 1 ] + [ -f "${BATS_FILE_TMPDIR}/site/film.js" ] + [ -f "${BATS_FILE_TMPDIR}/site/favicon.svg" ] +} + +@test "a module in a new group gets a scene of its own" { + copy_repo + mkdir -p "${ROOT}/modules/edge" + cat >"${ROOT}/modules/edge/gateway.sh" <<'EOF' +MOD_NAME="gateway" +MOD_GROUP="edge" +MOD_DESCRIPTION="Gateway in front of & more" +MOD_REQUIRES="system" +MOD_OPTIONS="port|8443|Port it listens on +mode||Optional mode" +EOF + run "${ROOT}/scripts/build-site.sh" "${ROOT}/out" + [ "${status}" -eq 0 ] + grep -qF 'id="group-edge"' "${ROOT}/out/index.html" + grep -qF 'Gateway in front of <everything> & more' "${ROOT}/out/index.html" + grep -qF 'LSS_GATEWAY_PORT=8443 LSS_GATEWAY_MODE=' "${ROOT}/out/index.html" + grep -qF '
              3. modules/edge
                4. ' "${ROOT}/out/index.html" + # Known groups keep their order; the new one comes after them. + [ "$(grep -n 'id="group-apps"' "${ROOT}/out/index.html" | cut -d: -f1)" -lt \ + "$(grep -n 'id="group-edge"' "${ROOT}/out/index.html" | cut -d: -f1)" ] +} + +@test "a module whose MOD_GROUP differs from its directory stops the build" { + copy_repo + sed -i 's/^MOD_GROUP="base"/MOD_GROUP="security"/' "${ROOT}/modules/base/swap.sh" + run "${ROOT}/scripts/build-site.sh" "${ROOT}/out" + [ "${status}" -eq 1 ] + [[ ${output} == *"modules/base/swap.sh: MOD_GROUP is 'security'."* ]] +} + +@test "the README tables have to match data/systems.conf" { + copy_repo + run "${ROOT}/scripts/build-site.sh" --check + [ "${status}" -eq 0 ] + sed -i 's/^system|Debian|12, 13|12, 13$/system|Debian|11, 12, 13|12, 13/' "${ROOT}/data/systems.conf" + sed -i 's/^requirement|Profile `devops`|1 GB; 1.5 GB on the RHEL family|7 GB|/requirement|Profile `devops`|1 GB|7 GB|/' \ + "${ROOT}/data/systems.conf" + run "${ROOT}/scripts/build-site.sh" --check + [ "${status}" -eq 1 ] + [[ ${output} == *'README.md "Supported systems" differs'* ]] + [[ ${output} == *'README.md "System requirements" differs'* ]] + run "${ROOT}/scripts/build-site.sh" "${ROOT}/out" + [ "${status}" -eq 1 ] + [ ! -e "${ROOT}/out/index.html" ] +}