Skip to content
13 changes: 9 additions & 4 deletions modules/capture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,19 @@ Bluetooth headset may switch to its call profile while it listens, and the syste
(ADR-0015's amendment of 2026-11-07); `me`'s first `device` says `headset: true` then, `false` for any
other microphone — absent where the graph does not read (D88). It is never part of a recording.

**`nstack e2e capture`** runs the scenarios without a call and without a voice: for about
three minutes the system's default output and input are two silent devices of its own, a note
**`nstack e2e capture`** runs the scenarios without a call and without a voice, sealed off the
computer's sound: in a bubblewrap (`bwrap`) whose `/dev` holds no sound card and which reaches
neither the desktop's PipeWire nor the system bus, on a PipeWire of its own that sees no
hardware — the computer's microphones, speakers and headsets, a pair of AirPods connecting
during the run included, cannot be opened, and the desktop's defaults are never moved: its
default output and input are two silent devices of its own, a note
is played into each, and the program records them in both forms — stopped as a user stops it,
read while it writes, left silent, killed, and with the same sound in both sources to see that
the tracks keep one clock. The second form's notes rest away from zero and carry two unequal
channels in 24 bits, so that a track centred, mixed or cut shows; and one source stops and
comes back. It runs nothing where there is no sound server, or while an application holds a
microphone; what it saw is in `.evidence/e2e.txt`, its logs in `$NSTACK_EVIDENCE/logs`
comes back. It runs nothing where PipeWire or `bwrap` is missing or where the system refuses
it a namespace, and stops at once, NOT RUN, if a device not its own shows in its graph, a sound
card is held, or the graph does not answer; what it saw is in `.evidence/e2e.txt`, its logs in `$NSTACK_EVIDENCE/logs`
(`.evidence/e2e/logs` when run alone), where nstack reads them after the run: a warning or an
error the manifest's `evidence.provoked` does not declare is said. A real call, a real microphone and a
headset stay a person's to try. Scenario P listens, stopped by `stop`, by a TERM signal and by its input closed, and with a named
Expand Down
233 changes: 201 additions & 32 deletions modules/capture/scripts/e2e.sh
Original file line number Diff line number Diff line change
@@ -1,28 +1,67 @@
#!/usr/bin/env bash
# The module's end-to-end scenarios (cycle 01, D3), on sound made here and on devices made
# for the run: nobody is recorded. It needs a PipeWire or PulseAudio desktop; where there is
# none — a CI runner — or where a microphone is in use, it says so and runs nothing.
#
# For about two minutes the system's default output and input are two silent devices of its
# own; they are put back whatever happens.
# for the run: nobody is recorded. The run is sealed off the computer's sound (2026-11-13: on the
# desktop's graph, AirPods connected during a run were taken as the default input):
# - in a bubblewrap of its own (bwrap, Flatpak's sandbox): a /dev with no /dev/snd — no sound card
# can be opened, through PipeWire or ALSA directly —, its own processes, and no desktop's
# runtime folder nor system bus — the desktop's graph and Bluetooth cannot be reached;
# - on a PipeWire, WirePlumber and pipewire-pulse of its own, as private_graph.sh's, no hardware
# monitored; a guard stops the run, NOT RUN, at anything there not its own.
# The desktop's defaults are never moved: read before and after, outside the seal, the same.
# Where PipeWire or bubblewrap is missing — a CI runner — it says so and runs nothing.
set -euo pipefail
cd "$(dirname "$0")/.."
mkdir -p .evidence
: > .evidence/e2e.txt
say() { echo "$*" | tee -a .evidence/e2e.txt; }
# The run's logs, where NapkinStack reads them after it (nstack e2e capture).
evidence=${NSTACK_EVIDENCE:-$PWD/.evidence/e2e}

if ! command -v pactl >/dev/null || ! pactl info >/dev/null 2>&1; then
say "e2e: NOT RUN — no sound server here"; exit 77
if [ -z "${KITOKEY_E2E_SEALED:-}" ]; then
: > .evidence/e2e.txt
command -v bwrap > /dev/null || { say "e2e: NOT RUN — bwrap (bubblewrap) is missing"; exit 77; }
command -v pactl > /dev/null || { say "e2e: NOT RUN — pactl is missing"; exit 77; }
desktop_defaults() { echo "$(pactl get-default-sink 2>/dev/null || echo none) $(pactl get-default-source 2>/dev/null || echo none)"; }
desktop_before=$(desktop_defaults)
# A /dev of its own, without /dev/snd; its own /proc and processes, all ended with it; the
# desktop's runtime folder (its PipeWire, its pulse) and the system bus (Bluetooth) hidden.
sealed=(bwrap --dev-bind / / --dev /dev --tmpfs /dev/shm --unshare-pid --proc /proc --die-with-parent)
for hidden in "${XDG_RUNTIME_DIR:-}" "/run/user/$(id -u)" /run/dbus /run/pulse /run/pipewire; do
[ -n "$hidden" ] && [ -d "$hidden" ] && sealed+=(--tmpfs "$hidden")
done
"${sealed[@]}" -- true 2>> .evidence/e2e.txt ||
{ say "e2e: NOT RUN — this system refuses the run a namespace of its own (bwrap)"; exit 77; }
# The run's folders, made out here and removed out here too: a TERM that ends this script ends
# the sealed one by SIGKILL (--die-with-parent), before its own cleaning can run (#796, S4).
work=$(mktemp -d)
graph=$(mktemp -d /tmp/wh-XXXXXX)
cleaned() {
# Once more after the sealed processes' last writes: they end with the seal, killed.
rm -rf "$work" "$graph" "$work.real" "$work.trial"; sleep 0.2; rm -rf "$work" "$graph" "$work.real" "$work.trial"
}
trap cleaned EXIT
trap 'exit 143' TERM
trap 'exit 130' INT
trap 'exit 129' HUP
status=0
"${sealed[@]}" --setenv KITOKEY_E2E_SEALED 1 --setenv KITOKEY_E2E_WORK "$work" --setenv KITOKEY_E2E_GRAPH "$graph" \
-- bash "$(realpath "$0")" "$@" || status=$?
say "The desktop's defaults, before and after the run: $desktop_before"
if [ "$(desktop_defaults)" = "$desktop_before" ]; then
say " ok the desktop's defaults the same"
else
say " FAIL the desktop's defaults now $(desktop_defaults): the run never speaks to them — a device plugged in meanwhile?"
[ "$status" = 0 ] && status=1
fi
exit "$status"
fi
if [ -n "$(pactl list short source-outputs)" ]; then
say "e2e: NOT RUN — an application holds a microphone: a call may be in progress"; exit 77
fi
if pactl list short sinks | awk -v d="$(pactl get-default-sink)" '$2 == d && $NF == "RUNNING" {found = 1} END {exit !found}'; then
say "e2e: NOT RUN — the system is playing sound: its output would be taken from it"; exit 77

# Sealed from here. No sound card in sight: the first of the guard's assertions.
if [ -e /dev/snd ] || { command -v aplay > /dev/null && ! aplay -l 2>&1 | grep -q 'no soundcards'; }; then
say "e2e: NOT RUN — a sound card is in sight inside the seal: $(ls /dev/snd 2>/dev/null | tr '\n' ' ')"; exit 77
fi
for tool in ffmpeg ffprobe pw-play pw-dump pw-cli pw-loopback pw-metadata python3; do
say "Sealed: /dev holds $(ls /dev | tr '\n' ' ')"

for tool in pipewire wireplumber pipewire-pulse pactl ffmpeg ffprobe pw-play pw-dump pw-cli pw-loopback pw-metadata python3; do
command -v "$tool" >/dev/null || { say "e2e: NOT RUN — $tool is missing"; exit 77; }
done

Expand All @@ -34,30 +73,156 @@ for _ in $(seq 60); do [ "$(cut -d. -f1 /proc/loadavg)" -lt "$quiet" ] && break;
if [ "$(cut -d. -f1 /proc/loadavg)" -ge "$quiet" ]; then
say "e2e: NOT RUN — the machine is busy (load $(cut -d' ' -f1 /proc/loadavg), $(nproc) processors): a clock cannot be measured on it"; exit 77
fi
bin=${CARGO_TARGET_DIR:-$PWD/target}/release/kitokey-capture # where cargo built it
work=$(mktemp -d)
bin=$(realpath "${CARGO_TARGET_DIR:-$PWD/target}/release/kitokey-capture") # where cargo built it
work=${KITOKEY_E2E_WORK:-$(mktemp -d)} # made by the part outside the seal, which removes it
# Its logs in the run's evidence, this run's alone, never the user's (ADR-0007).
export KITOKEY_LOG_DIR="$evidence/logs"
rm -rf "$KITOKEY_LOG_DIR"
# A run that was killed outright could not put anything back: its devices are removed first,
# and the system falls back on its own.
for stale in $(pactl list short modules | awk '/(kitokey|wholeheard)_e2e_/ {print $1}'); do
say "e2e: a device of an earlier run that was killed is removed"; pactl unload-module "$stale" || true
done
old_sink=$(pactl get-default-sink); old_source=$(pactl get-default-source)
out=$(pactl load-module module-null-sink sink_name=kitokey_e2e_out)
mic=$(pactl load-module module-null-sink sink_name=kitokey_e2e_mic)

# The run's own graph, as private_graph.sh's. A socket's path is short: never under a long folder.
graph=${KITOKEY_E2E_GRAPH:-$(mktemp -d /tmp/wh-XXXXXX)}
export XDG_RUNTIME_DIR=$graph/rt PIPEWIRE_RUNTIME_DIR=$graph/rt XDG_CONFIG_HOME=$graph/cfg XDG_STATE_HOME=$graph/state
export XDG_CACHE_HOME=$graph/cache XDG_DATA_HOME=$graph/data DBUS_SESSION_BUS_ADDRESS=disabled:
unset PIPEWIRE_REMOTE PULSE_SERVER DISPLAY WAYLAND_DISPLAY
mkdir -p "$graph/rt" "$graph/cfg/wireplumber/wireplumber.conf.d" "$graph/cfg/pipewire/pipewire-pulse.conf.d"
chmod 700 "$graph/rt"
cat > "$graph/cfg/wireplumber/wireplumber.conf.d/90-no-hardware.conf" <<CONF
wireplumber.profiles = { main = { monitor.alsa = disabled, monitor.bluez = disabled, monitor.bluez-midi = disabled, monitor.alsa-midi = disabled, monitor.v4l2 = disabled, monitor.libcamera = disabled, support.logind = disabled, support.reserve-device = disabled, support.portal-permissionstore = disabled } }
CONF
# pipewire-pulse's fallback sink, `auto_null`, off where its own configuration says it is: only the
# run's sinks in this graph (2026-11-13, a guard stopping every run at it).
cat > "$graph/cfg/pipewire/pipewire-pulse.conf.d/90-no-always-sink.conf" <<CONF
pulse.properties = { pulse.cmd.always-sink = false }
CONF
pipewire > "$graph/pipewire.log" 2>&1 & daemon=$!
for _ in $(seq 20); do [ -S "$graph/rt/pipewire-0" ] && break; sleep 0.25; done
wireplumber > "$graph/wireplumber.log" 2>&1 & manager=$!
pipewire-pulse > "$graph/pipewire-pulse.log" 2>&1 & pulse=$!
for _ in $(seq 20); do pactl info > /dev/null 2>&1 && break; sleep 0.25; done
restore() {
status=$?
# Cleaning is never cut short: `timeout` signals the script, then its whole group, a second TERM.
trap '' TERM INT HUP
pkill -P $$ 2>/dev/null || true
pactl set-default-sink "$old_sink" 2>/dev/null || true
pactl set-default-source "$old_source" 2>/dev/null || true
pactl unload-module "$out" 2>/dev/null || true
pactl unload-module "$mic" 2>/dev/null || true
# Scenario J's own, when it was stopped before it took them away.
for module in ${mic_b:-} ${out_b:-} ${out_c:-} ${mic_c:-} ${mic_d:-}; do pactl unload-module "$module" 2>/dev/null || true; done
rm -rf "$work"
# The graph's daemons by their PIDs, killed outright if they have not ended within two seconds.
kill "$pulse" "$manager" "$daemon" 2>/dev/null || true
for _ in $(seq 20); do
alive=0; for p in "$pulse" "$manager" "$daemon"; do kill -0 "$p" 2>/dev/null && alive=1; done
[ "$alive" = 0 ] && break; sleep 0.1
done
kill -KILL "$pulse" "$manager" "$daemon" 2>/dev/null || true
wait "$pulse" "$manager" "$daemon" 2>/dev/null || true
rm -rf "$work" "$graph"
if [ -e "$work.real" ]; then
say "e2e: NOT RUN — a real device appeared: $(cat "$work.real")"
# The guard's trial passes only stopped by its intruder: stopped by anything else, or not at all, it fails.
if [ -n "${E2E_INTRUDER:-}" ] && ! grep -q "intruder_${E2E_INTRUDER%%:*}" "$work.real"; then
say " FAIL the guard stopped the run, not at intruder_${E2E_INTRUDER%%:*}"; rm -f "$work.real" "$work.trial"; exit 1
fi
rm -f "$work.real" "$work.trial"; exit 77
fi
if [ -e "$work.trial" ]; then say " FAIL $(cat "$work.trial")"; rm -f "$work.trial"; exit 1; fi
if [ -n "${E2E_INTRUDER:-}" ]; then say " FAIL the guard let intruder_${E2E_INTRUDER%%:*} through"; exit 1; fi
exit "$status"
}
trap restore EXIT
# A TERM is a stop, never a skip: the guard's own says NOT RUN through "$work.real", read in restore.
trap 'exit 143' TERM
trap 'exit 130' INT
trap 'exit 129' HUP

# The guard, the whole run long, failing closed: the graph read (an answer late or empty stops the
# run), no device in it, no source or sink but the run's own `kitokey_e2e_*`, and no process of the
# run — every process in the seal is — holding anything under /dev/snd (`pcm*`, `control*`). One seen:
# every capture and the graph's daemon killed at once; the script ends at its next step (a scenario's
# `sleep` runs out first, the sound already cut), NOT RUN — exit 77, as a run that cannot run here
# (.nstack/handbook/09-platform.md).
real_devices() {
PATH="${trial_bin:-}$PATH" python3 - <<'GUARD'
import json, os, subprocess, sys
seen = []
try:
dump = json.loads(subprocess.run(["pw-dump"], capture_output=True, text=True, timeout=3).stdout or "null")
except (subprocess.TimeoutExpired, ValueError):
dump = None
if not dump:
seen.append("the run's graph did not answer pw-dump: nothing seen is not nothing there")
# A device of any kind, or a source or sink not the run's own: streams (Stream/…) are the programs'.
for obj in dump or []:
props = (obj.get("info") or {}).get("props") or {}
name = str(props.get("node.name") or props.get("device.name") or obj.get("id"))
device = obj.get("type", "").endswith(":Device")
stranger = str(props.get("media.class", "")).startswith("Audio/") and not name.startswith("kitokey_e2e_")
if device or stranger:
seen.append(f"{name} ({props.get('media.class') or obj.get('type')})")
for pid in filter(str.isdigit, os.listdir("/proc")):
try:
held = [os.readlink(f"/proc/{pid}/fd/{fd}") for fd in os.listdir(f"/proc/{pid}/fd")]
except OSError:
continue
seen += [f"{card} held by {pid}" for card in held if card.startswith("/dev/snd/")]
print(", ".join(seen))
sys.exit(1 if seen else 0)
GUARD
}
stop_all() {
echo "$1" > "$work.real"
for pid in /proc/[0-9]*; do
[ "$(readlink "$pid/exe" 2>/dev/null)" = "$bin" ] && kill -KILL "${pid#/proc/}" 2>/dev/null
done
kill -KILL "$daemon" 2>/dev/null || true
kill -TERM $$
}
# The device trial's intruder: no Device factory runs without hardware or a bus (the installed SPA
# ones are api.alsa.{pcm,acp,compress.offload}.device, api.bluez5.device, api.libcamera.device), and
# `api.alsa.enum.udev` in the seal made none (2026-11-14). The guard's pw-dump answers for it then: the
# graph's own dump, and the Device as pw-dump prints one once the trial brings it.
if [[ ${E2E_INTRUDER:-} == device:* ]]; then
mkdir -p "$graph/trial" && trial_bin=$graph/trial:
cat > "$graph/trial/pw-dump" <<SHIM
#!/bin/sh
$(command -v pw-dump) | python3 -c '
import json, os, sys
dump = json.load(sys.stdin)
if os.path.exists("$graph/intruder_device"):
dump.append({"id": 100000, "type": "PipeWire:Interface:Device", "info": {"props": {"device.name": "intruder_device"}}})
json.dump(dump, sys.stdout)'
SHIM
chmod +x "$graph/trial/pw-dump"
fi
if ! seen=$(real_devices); then stop_all "$seen"; fi
( while sleep 0.5; do seen=$(real_devices) || { stop_all "$seen"; break; }; done ) & guard=$!
# The guard's own trial: E2E_INTRUDER=<sink|source|device>:<seconds> brings one not the run's that
# long after the start, as a headset or a card appearing — the run must end NOT RUN, exit 77, naming it
# (`intruder_sink`, `intruder_source`, `intruder_device`); stopped by anything else, or not, it fails.
# The trial ends at once when it proves nothing: its intruder not in the guard's pw-dump within 3 s,
# or there and the run not stopped 3 s later — never a whole run to learn it.
if [ -n "${E2E_INTRUDER:-}" ]; then
(
kind=${E2E_INTRUDER%%:*}
sleep "${E2E_INTRUDER#*:}"
case $kind in
sink) pactl load-module module-null-sink sink_name=intruder_sink > /dev/null ;;
source) pw-cli create-node adapter factory.name=support.null-audio-sink node.name=intruder_source \
media.class=Audio/Source/Virtual object.linger=true audio.position=[FL,FR] > /dev/null ;;
device) touch "$graph/intruder_device" ;;
esac
there=
for _ in $(seq 12); do
if PATH="${trial_bin:-}$PATH" pw-dump 2>/dev/null | grep -q "\"intruder_$kind\""; then there=1; break; fi
sleep 0.25
done
if [ -z "$there" ]; then # the guard may have stopped the graph first: then it saw it
[ -e "$work.real" ] || { echo "the trial's intruder did not appear: intruder_$kind" > "$work.trial"; kill -TERM $$; }
exit 0
fi
sleep 3
echo "the guard let intruder_$kind through" > "$work.trial"; kill -TERM $$
) &
fi

out=$(pactl load-module module-null-sink sink_name=kitokey_e2e_out)
mic=$(pactl load-module module-null-sink sink_name=kitokey_e2e_mic)
pactl set-default-sink kitokey_e2e_out
pactl set-default-source kitokey_e2e_mic.monitor

Expand Down Expand Up @@ -191,6 +356,7 @@ for run in part flac again; do
eval "recorder_$run=$!"
done
sleep 65
signallers=()
for run in part flac again; do
folder=$(ls -d "$work/kept-$run"/*/ | head -1)
pid=$(eval echo "\$recorder_$run")
Expand All @@ -199,12 +365,14 @@ for run in part flac again; do
flac) python3 scripts/e2e_measure_v2.py signal-at "$folder" "$pid" SIGKILL local.flac & ;;
again) python3 scripts/e2e_measure_v2.py signal-at "$folder" "$pid" SIGTERM local.flac.part & ;;
esac
signallers+=("$!")
done
sleep 0.5
kill -INT "$recorder_part" "$recorder_flac" "$recorder_again"
wait "$recorder_part" "$recorder_flac" 2>/dev/null || true
again_as=0; wait "$recorder_again" || again_as=$?
wait
# Its signallers alone: the graph's daemons are children of this script too, and never end.
wait "${signallers[@]}" 2>/dev/null || true
kill "$mic_player" "$others_player" 2>/dev/null || true
for run in part flac again; do
folder=$(ls -d "$work/kept-$run"/*/ | head -1)
Expand Down Expand Up @@ -722,5 +890,6 @@ PY
check headset_said_once
check unchanged

kill "$guard" 2>/dev/null || true; wait "$guard" 2>/dev/null || true
[ "$failed" = 0 ] && say "e2e: passed" || say "e2e: FAILED"
exit "$failed"
Loading