feat(guanghu-os): add pre-root supervisor source slice

This commit is contained in:
冰朔 2026-08-15 23:16:37 +08:00
commit 29bb023455
13 changed files with 403 additions and 3 deletions

View file

@ -94,6 +94,24 @@ host. It cannot prove Guanghu-first boot control or the final topology. Those
remain `0` until the same lifecycle is owned by an independently booted
Guanghu supervisor and has a current JD server receipt.
## Pre-root Guanghu supervisor source slice
`scripts/guanghu-first-boot-supervisor.sh` and the matching initramfs-tools
hook move the first deterministic Guanghu control state ahead of the complete
Ubuntu root filesystem. The pre-root step binds the exact JD DMI instance,
root UUID, boot ID, explicit `guanghu.first_boot=1` kernel marker, preserved
Linux rescue entry, and repository bridge. It then writes one boot-scoped
handoff under `/run/guanghu/first-boot` while the complete Linux userspace is
still classified as dormant.
`scripts/build-guanghu-first-boot-initramfs.sh` builds a candidate without
changing the installed initramfs, GRUB, disk, or boot default. Path overrides
are accepted only inside the isolated test harness. The source contract and
fixture test do not prove that a Guanghu supervisor remains alive across
`switch_root`; independent first-boot control, physical deployment, and full
on-demand Linux subcontrol therefore remain `0` until separate QEMU and JD
receipts exist. See ADR-0176.
## Language-primary boot target
`guanghu-language-primary.target` makes the accepted cognitive-control model

View file

@ -0,0 +1,6 @@
schema=guanghu.first-boot-supervisor/v1
node_id=JD-FD-PRIMARY
instance_id=f3d4b730-7f02-452f-975b-7091a4800431
root_uuid=9e4550a0-452b-4f28-b5a5-d5364aa450f6
linux_rescue_entry=gnulinux-simple-9e4550a0-452b-4f28-b5a5-d5364aa450f6
linux_code_bridge=hlcc-jd-candidate.service

View file

@ -0,0 +1,17 @@
#!/bin/sh
set -eu
PREREQ=""
prereqs() { echo "${PREREQ}"; }
case "${1:-}" in prereqs) prereqs; exit 0 ;; esac
. /usr/share/initramfs-tools/hook-functions
: "${GUANGHU_FIRST_BOOT_SUPERVISOR_SOURCE:?supervisor source is required}"
: "${GUANGHU_FIRST_BOOT_CONFIG_SOURCE:?configuration source is required}"
: "${GUANGHU_FIRST_BOOT_GRUB_SOURCE:?GRUB snapshot source is required}"
copy_exec "${GUANGHU_FIRST_BOOT_SUPERVISOR_SOURCE}" /usr/lib/guanghu/guanghu-first-boot-supervisor
copy_file config "${GUANGHU_FIRST_BOOT_CONFIG_SOURCE}" /etc/guanghu/first-boot-supervisor.conf
copy_file config "${GUANGHU_FIRST_BOOT_GRUB_SOURCE}" /etc/guanghu/grub.cfg.snapshot
chmod 0600 "${DESTDIR}/etc/guanghu/first-boot-supervisor.conf"

View file

@ -0,0 +1,13 @@
#!/bin/sh
set -eu
PREREQ=""
prereqs() { echo "${PREREQ}"; }
case "${1:-}" in prereqs) prereqs; exit 0 ;; esac
. /scripts/functions
if ! /usr/lib/guanghu/guanghu-first-boot-supervisor pre-root; then
panic "Guanghu pre-root authority validation failed; refusing root handoff"
exit 1
fi

View file

@ -0,0 +1,53 @@
#!/usr/bin/env bash
set -Eeuo pipefail
[[ $# -ge 3 && $# -le 4 ]] || {
echo "usage: build-guanghu-first-boot-initramfs.sh <output> <config> <grub-snapshot> [kernel-version]" >&2
exit 64
}
output=$(readlink -m "$1")
config=$(readlink -f "$2")
grub_snapshot=$(readlink -f "$3")
kernel_version=${4:-$(uname -r)}
source_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
supervisor=${source_root}/scripts/guanghu-first-boot-supervisor.sh
packaging=${source_root}/packaging/initramfs-tools
command -v mkinitramfs >/dev/null
[[ -r /etc/initramfs-tools/initramfs.conf ]] || {
echo "host initramfs configuration is unavailable" >&2
exit 1
}
[[ -f ${config} && ! -L ${config} ]] || {
echo "first-boot configuration is missing or unsafe" >&2
exit 1
}
[[ -f ${grub_snapshot} && ! -L ${grub_snapshot} ]] || {
echo "GRUB snapshot is missing or unsafe" >&2
exit 1
}
grep -Fqx 'schema=guanghu.first-boot-supervisor/v1' "${config}"
grep -Fq 'gnulinux-simple-' "${grub_snapshot}"
build_root=$(mktemp -d)
trap 'rm -rf "${build_root}"' EXIT
mkdir -p "${build_root}/conf.d" "${build_root}/hooks" \
"${build_root}/scripts/local-premount" \
"$(dirname "${output}")"
install -m 0644 /etc/initramfs-tools/initramfs.conf "${build_root}/initramfs.conf"
install -m 0644 /dev/null "${build_root}/modules"
cp "${packaging}/hooks/guanghu-first-boot-supervisor" "${build_root}/hooks/"
cp "${packaging}/scripts/local-premount/guanghu-first-boot-supervisor" \
"${build_root}/scripts/local-premount/"
chmod 0755 "${build_root}/hooks/guanghu-first-boot-supervisor" \
"${build_root}/scripts/local-premount/guanghu-first-boot-supervisor"
export GUANGHU_FIRST_BOOT_SUPERVISOR_SOURCE=${supervisor}
export GUANGHU_FIRST_BOOT_CONFIG_SOURCE=${config}
export GUANGHU_FIRST_BOOT_GRUB_SOURCE=${grub_snapshot}
mkinitramfs -d "${build_root}" -o "${output}" "${kernel_version}"
chmod 0600 "${output}"
sha256sum "${output}" >"${output}.sha256"
printf 'GUANGHU_FIRST_BOOT_INITRAMFS_BUILT kernel=%s output=%s\n' \
"${kernel_version}" "${output}"

View file

@ -0,0 +1,127 @@
#!/bin/sh
set -eu
die() {
printf 'GUANGHU_FIRST_BOOT_SUPERVISOR_FAIL_0: %s\n' "$1" >&2
exit 1
}
test_root=${GUANGHU_FIRST_BOOT_TEST_ROOT:-}
if [ -n "${test_root}" ]; then
test_root=$(readlink -f "${test_root}")
[ -d "${test_root}" ] || die "test root is unavailable"
config_path=${GUANGHU_FIRST_BOOT_CONFIG:-}
state_root=${GUANGHU_FIRST_BOOT_STATE_ROOT:-}
dmi_path=${GUANGHU_FIRST_BOOT_DMI_PATH:-}
cmdline_path=${GUANGHU_FIRST_BOOT_CMDLINE_PATH:-}
boot_id_path=${GUANGHU_FIRST_BOOT_BOOT_ID_PATH:-}
grub_path=${GUANGHU_FIRST_BOOT_GRUB_PATH:-}
for override_path in "${config_path}" "${state_root}" "${dmi_path}" \
"${cmdline_path}" "${boot_id_path}" "${grub_path}"; do
resolved_path=$(readlink -f "${override_path}")
case "${resolved_path}" in
"${test_root}"|"${test_root}"/*) ;;
*) die "test path escapes the isolated root" ;;
esac
done
else
[ -z "${GUANGHU_FIRST_BOOT_CONFIG:-}${GUANGHU_FIRST_BOOT_STATE_ROOT:-}${GUANGHU_FIRST_BOOT_DMI_PATH:-}${GUANGHU_FIRST_BOOT_CMDLINE_PATH:-}${GUANGHU_FIRST_BOOT_BOOT_ID_PATH:-}${GUANGHU_FIRST_BOOT_GRUB_PATH:-}" ] ||
die "production path overrides are forbidden"
config_path=/etc/guanghu/first-boot-supervisor.conf
state_root=/run/guanghu/first-boot
dmi_path=/sys/class/dmi/id/product_uuid
cmdline_path=/proc/cmdline
boot_id_path=/proc/sys/kernel/random/boot_id
grub_path=/etc/guanghu/grub.cfg.snapshot
fi
[ -f "${config_path}" ] && [ ! -L "${config_path}" ] || die "configuration is missing or unsafe"
mode=$(stat -c '%a' "${config_path}" 2>/dev/null || stat -f '%Lp' "${config_path}")
[ "${mode}" = 600 ] || die "configuration mode must be 0600"
if [ -z "${test_root}" ]; then
owner=$(stat -c '%u' "${config_path}" 2>/dev/null || stat -f '%u' "${config_path}")
[ "${owner}" = 0 ] || die "configuration must be root-owned"
fi
schema=
node_id=
instance_id=
root_uuid=
linux_rescue_entry=
linux_code_bridge=
while IFS='=' read -r key value; do
case "${key}" in
schema) schema=${value} ;;
node_id) node_id=${value} ;;
instance_id) instance_id=${value} ;;
root_uuid) root_uuid=${value} ;;
linux_rescue_entry) linux_rescue_entry=${value} ;;
linux_code_bridge) linux_code_bridge=${value} ;;
''|'#'*) ;;
*) die "unknown configuration field ${key}" ;;
esac
done <"${config_path}"
[ "${schema}" = 'guanghu.first-boot-supervisor/v1' ] || die "configuration schema mismatch"
[ "${node_id}" = 'JD-FD-PRIMARY' ] || die "node identity mismatch"
printf '%s' "${instance_id}" | grep -Eq '^[0-9a-f-]{36}$' || die "instance id is malformed"
printf '%s' "${root_uuid}" | grep -Eq '^[0-9a-f-]{36}$' || die "root UUID is malformed"
printf '%s' "${linux_rescue_entry}" | grep -Eq '^gnulinux-simple-[0-9a-f-]{36}$' || die "rescue entry is malformed"
printf '%s' "${linux_code_bridge}" | grep -Eq '^[A-Za-z0-9_.@-]+\.service$' || die "code bridge unit is malformed"
[ -r "${dmi_path}" ] || die "DMI identity is unavailable"
observed_instance=$(tr 'A-F' 'a-f' <"${dmi_path}" | tr -d '\r\n')
[ "${observed_instance}" = "${instance_id}" ] || die "DMI identity mismatch"
[ -r "${cmdline_path}" ] || die "kernel command line is unavailable"
cmdline=$(cat "${cmdline_path}")
case " ${cmdline} " in *' guanghu.first_boot=1 '*) ;; *) die "explicit first-boot marker is missing" ;; esac
case " ${cmdline} " in *" root=UUID=${root_uuid} "*) ;; *) die "root UUID binding is missing" ;; esac
[ -r "${grub_path}" ] || die "embedded rescue snapshot is unavailable"
grep -Fq "${linux_rescue_entry}" "${grub_path}" || die "Linux rescue entry is not preserved"
[ -r "${boot_id_path}" ] || die "boot id is unavailable"
boot_id=$(tr -d '\r\n' <"${boot_id_path}")
printf '%s' "${boot_id}" | grep -Eq '^[0-9a-f-]{36}$' || die "boot id is malformed"
mkdir -p "${state_root}"
handoff_path=${state_root}/handoff.json
write_handoff() {
temporary_path=${handoff_path}.tmp.$$
printf '%s\n' \
"{\"schema\":\"guanghu.first-boot-handoff/v1\",\"node_id\":\"${node_id}\",\"instance_id\":\"${instance_id}\",\"boot_id\":\"${boot_id}\",\"control\":\"GUANGHU_OS\",\"stage\":\"PRE_ROOT_SUPERVISOR_ACTIVE\",\"linux_kernel_role\":\"HARDWARE_COMPATIBILITY_SUBSTRATE\",\"full_linux_userspace\":\"DORMANT\",\"linux_code_bridge\":\"PENDING_BOUNDED_HANDOFF\",\"linux_rescue\":\"${linux_rescue_entry}\"}" \
>"${temporary_path}"
chmod 0600 "${temporary_path}"
mv "${temporary_path}" "${handoff_path}"
}
verify_handoff() {
[ -f "${handoff_path}" ] && [ ! -L "${handoff_path}" ] || die "first-boot handoff is missing or unsafe"
handoff=$(cat "${handoff_path}")
for binding in \
'"schema":"guanghu.first-boot-handoff/v1"' \
"\"node_id\":\"${node_id}\"" \
"\"instance_id\":\"${instance_id}\"" \
"\"boot_id\":\"${boot_id}\"" \
'"control":"GUANGHU_OS"' \
'"stage":"PRE_ROOT_SUPERVISOR_ACTIVE"' \
'"full_linux_userspace":"DORMANT"' \
'"linux_code_bridge":"PENDING_BOUNDED_HANDOFF"' \
"\"linux_rescue\":\"${linux_rescue_entry}\""; do
printf '%s' "${handoff}" | grep -Fq "${binding}" || die "handoff binding mismatch"
done
}
case "${1:-}" in
pre-root)
write_handoff
verify_handoff
printf 'GUANGHU_FIRST_BOOT_SUPERVISOR_ACTIVE node=%s boot_id=%s linux_userspace=DORMANT\n' \
"${node_id}" "${boot_id}"
;;
verify-handoff)
verify_handoff
printf 'GUANGHU_FIRST_BOOT_HANDOFF_VERIFIED node=%s boot_id=%s\n' \
"${node_id}" "${boot_id}"
;;
*) die "usage: guanghu-first-boot-supervisor <pre-root|verify-handoff>" ;;
esac

View file

@ -0,0 +1,104 @@
#!/usr/bin/env bash
set -Eeuo pipefail
source_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
supervisor=${source_root}/scripts/guanghu-first-boot-supervisor.sh
hook=${source_root}/packaging/initramfs-tools/hooks/guanghu-first-boot-supervisor
premount=${source_root}/packaging/initramfs-tools/scripts/local-premount/guanghu-first-boot-supervisor
builder=${source_root}/scripts/build-guanghu-first-boot-initramfs.sh
fixture=$(mktemp -d)
trap 'rm -rf "${fixture}"' EXIT
mkdir -p "${fixture}/proc/sys/kernel/random" "${fixture}/dmi" \
"${fixture}/grub" "${fixture}/run"
printf '%s\n' 'f3d4b730-7f02-452f-975b-7091a4800431' >"${fixture}/dmi/product_uuid"
printf '%s\n' '68d4a3c9-c866-4f4a-be2e-0aa5f41a61b1' \
>"${fixture}/proc/sys/kernel/random/boot_id"
printf '%s\n' \
'console=ttyS0 guanghu.first_boot=1 root=UUID=9e4550a0-452b-4f28-b5a5-d5364aa450f6 ro' \
>"${fixture}/proc/cmdline"
printf '%s\n' \
"menuentry 'Ubuntu rescue' 'gnulinux-simple-9e4550a0-452b-4f28-b5a5-d5364aa450f6'" \
>"${fixture}/grub/grub.cfg"
cat >"${fixture}/supervisor.conf" <<'EOF'
schema=guanghu.first-boot-supervisor/v1
node_id=JD-FD-PRIMARY
instance_id=f3d4b730-7f02-452f-975b-7091a4800431
root_uuid=9e4550a0-452b-4f28-b5a5-d5364aa450f6
linux_rescue_entry=gnulinux-simple-9e4550a0-452b-4f28-b5a5-d5364aa450f6
linux_code_bridge=hlcc-jd-candidate.service
EOF
chmod 0600 "${fixture}/supervisor.conf"
env \
GUANGHU_FIRST_BOOT_TEST_ROOT="${fixture}" \
GUANGHU_FIRST_BOOT_CONFIG="${fixture}/supervisor.conf" \
GUANGHU_FIRST_BOOT_STATE_ROOT="${fixture}/run" \
GUANGHU_FIRST_BOOT_DMI_PATH="${fixture}/dmi/product_uuid" \
GUANGHU_FIRST_BOOT_CMDLINE_PATH="${fixture}/proc/cmdline" \
GUANGHU_FIRST_BOOT_BOOT_ID_PATH="${fixture}/proc/sys/kernel/random/boot_id" \
GUANGHU_FIRST_BOOT_GRUB_PATH="${fixture}/grub/grub.cfg" \
"${supervisor}" pre-root
python3 - "${fixture}/run/handoff.json" <<'PY'
import json
import pathlib
import sys
state = json.loads(pathlib.Path(sys.argv[1]).read_text())
assert state == {
"schema": "guanghu.first-boot-handoff/v1",
"node_id": "JD-FD-PRIMARY",
"instance_id": "f3d4b730-7f02-452f-975b-7091a4800431",
"boot_id": "68d4a3c9-c866-4f4a-be2e-0aa5f41a61b1",
"control": "GUANGHU_OS",
"stage": "PRE_ROOT_SUPERVISOR_ACTIVE",
"linux_kernel_role": "HARDWARE_COMPATIBILITY_SUBSTRATE",
"full_linux_userspace": "DORMANT",
"linux_code_bridge": "PENDING_BOUNDED_HANDOFF",
"linux_rescue": "gnulinux-simple-9e4550a0-452b-4f28-b5a5-d5364aa450f6",
}
PY
env \
GUANGHU_FIRST_BOOT_TEST_ROOT="${fixture}" \
GUANGHU_FIRST_BOOT_CONFIG="${fixture}/supervisor.conf" \
GUANGHU_FIRST_BOOT_STATE_ROOT="${fixture}/run" \
GUANGHU_FIRST_BOOT_DMI_PATH="${fixture}/dmi/product_uuid" \
GUANGHU_FIRST_BOOT_CMDLINE_PATH="${fixture}/proc/cmdline" \
GUANGHU_FIRST_BOOT_BOOT_ID_PATH="${fixture}/proc/sys/kernel/random/boot_id" \
GUANGHU_FIRST_BOOT_GRUB_PATH="${fixture}/grub/grub.cfg" \
"${supervisor}" verify-handoff
cp "${fixture}/proc/cmdline" "${fixture}/proc/cmdline.good"
printf '%s\n' 'console=ttyS0 root=UUID=9e4550a0-452b-4f28-b5a5-d5364aa450f6 ro' \
>"${fixture}/proc/cmdline"
if env \
GUANGHU_FIRST_BOOT_TEST_ROOT="${fixture}" \
GUANGHU_FIRST_BOOT_CONFIG="${fixture}/supervisor.conf" \
GUANGHU_FIRST_BOOT_STATE_ROOT="${fixture}/run" \
GUANGHU_FIRST_BOOT_DMI_PATH="${fixture}/dmi/product_uuid" \
GUANGHU_FIRST_BOOT_CMDLINE_PATH="${fixture}/proc/cmdline" \
GUANGHU_FIRST_BOOT_BOOT_ID_PATH="${fixture}/proc/sys/kernel/random/boot_id" \
GUANGHU_FIRST_BOOT_GRUB_PATH="${fixture}/grub/grub.cfg" \
"${supervisor}" pre-root >/dev/null 2>&1; then
echo "first-boot supervisor accepted a boot without its explicit kernel marker" >&2
exit 1
fi
mv "${fixture}/proc/cmdline.good" "${fixture}/proc/cmdline"
if GUANGHU_FIRST_BOOT_CONFIG="${fixture}/supervisor.conf" \
"${supervisor}" pre-root >/dev/null 2>&1; then
echo "production mode accepted path overrides" >&2
exit 1
fi
grep -Fq 'copy_exec "${GUANGHU_FIRST_BOOT_SUPERVISOR_SOURCE}" /usr/lib/guanghu/guanghu-first-boot-supervisor' "${hook}"
grep -Fq '. /scripts/functions' "${premount}"
grep -Fq 'if ! /usr/lib/guanghu/guanghu-first-boot-supervisor pre-root; then' "${premount}"
grep -Fq 'panic "Guanghu pre-root authority validation failed; refusing root handoff"' "${premount}"
grep -Fq 'PREREQ=""' "${premount}"
grep -Fq 'install -m 0644 /etc/initramfs-tools/initramfs.conf "${build_root}/initramfs.conf"' "${builder}"
grep -Fq 'install -m 0644 /dev/null "${build_root}/modules"' "${builder}"
echo GUANGHU_FIRST_BOOT_SUPERVISOR_CONTRACT_OK

View file

@ -94,6 +94,8 @@ run_gate shell_syntax bash -c \
_ "${source_root}"
run_gate linux_subcontrol_docker_backend \
"${source_root}/scripts/test-linux-subcontrol-docker-backend.sh"
run_gate guanghu_first_boot_supervisor \
"${source_root}/scripts/test-guanghu-first-boot-supervisor.sh"
run_gate auditable_line_coverage_100_percent \
bash -c '
cargo llvm-cov clean --workspace --manifest-path "$1/Cargo.toml"