diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index be6626ce..79266717 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -48,6 +48,7 @@ jobs: steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + persist-credentials: false # The pull request's merge commit and its first parent, the base branch. fetch-depth: 2 - id: diff @@ -55,9 +56,7 @@ jobs: EVENT: ${{ github.event_name }} run: | if [ "$EVENT" != pull_request ]; then - echo "code=true" >> "$GITHUB_OUTPUT" - echo "diarize=true" >> "$GITHUB_OUTPUT" - echo "gpu=true" >> "$GITHUB_OUTPUT" + printf '%s\n' code=true diarize=true gpu=true >> "$GITHUB_OUTPUT" exit 0 fi git diff --name-only HEAD^1 HEAD > changed.txt @@ -88,6 +87,8 @@ jobs: timeout-minutes: ${{ inputs.repeat > 1 && 180 || 30 }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version-file: .bun-version @@ -173,6 +174,8 @@ jobs: TEST_REPEAT: ${{ inputs.repeat || 1 }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version-file: .bun-version @@ -220,7 +223,7 @@ jobs: echo echo "Every parity screen, dark and light: $URL" echo - ls ui-shots | sed 's/^/- /' + for shot in ui-shots/*.png; do echo "- ${shot#ui-shots/}"; done } >> "$GITHUB_STEP_SUMMARY" # The capture helper (native/akou-capture) on every OS: format, lint, unit and engine tests, both @@ -245,6 +248,8 @@ jobs: shell: bash steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Rust 1.97.1 run: | rustup toolchain install 1.97.1 --profile minimal --component clippy,rustfmt @@ -964,6 +969,8 @@ jobs: TEST_REPEAT: ${{ inputs.repeat || 1 }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Rust 1.97.1 run: | rustup toolchain install 1.97.1 --profile minimal @@ -1042,7 +1049,10 @@ jobs: command -v setfacl >/dev/null || sudo apt-get install -y -qq acl mkfifo kb.fifo mouse.fifo exec 4<>kb.fifo 5<>mouse.fifo + # This user's shell opens the fifos and the output files; only the device writer is root. + # shellcheck disable=SC2024 sudo python3 uinput.py keyboard kb.out & + # shellcheck disable=SC2024 sudo python3 uinput.py mouse mouse.out & node() { for d in /sys/class/input/event*; do @@ -1081,6 +1091,8 @@ jobs: cat "$1.err" } check() { if ! eval "$1"; then echo "FAILED: $2"; exit 1; fi; } + # check() evals this string, so it is single-quoted on purpose. + # shellcheck disable=SC2016 check '! test -r "$kb"' "the virtual keyboard is readable before the ACL; the control proves nothing" hold control RightControl 4 97 check '! grep -q "\"type\":\"session.started\"" control.err' "a session started with the keyboard unreadable" @@ -1091,6 +1103,8 @@ jobs: hold keys RightControl 4 97 check 'grep -q "\"type\":\"session.started\"" keys.err' "a held Right Control started no session" check 'grep -q "\"type\":\"session.ended\",\"id\":\"[^\"]*\",\"reason\":\"release\"" keys.err' "the release did not end the session" + # check() evals this string, so it is single-quoted on purpose. + # shellcheck disable=SC2016 check '[ "$(head -c 4 keys.akp)" = AKP1 ]' "no audio packets on stdout" check 'grep -q "\"type\":\"key\",\"name\":\"A\"" keys.err' "the recorder did not report A" hold mouse Mouse4 5 275 @@ -1177,9 +1191,13 @@ jobs: check '[ ! -s music.out ] && [ ! -s podcast.out ]' "a player was touched with pause_media never sent" run paused '{"type":"pause_media","on":true}' '{"type":"session.start"}' '{"type":"session.stop"}' '{"type":"stop"}' check 'grep -q "after {\"type\":\"session.start\"}: Pause $" paused.log' "the playing player was not paused while listening" + # check() evals this string, so it is single-quoted on purpose. + # shellcheck disable=SC2016 check '[ "$(tr "\n" " " < music.out)" = "Pause Play " ]' "the playing player was not given back once at the end" check '[ ! -s podcast.out ]' "the paused player was touched" run stopped '{"type":"pause_media","on":true}' '{"type":"session.start"}' '{"type":"stop"}' + # check() evals this string, so it is single-quoted on purpose. + # shellcheck disable=SC2016 check '[ "$(tr "\n" " " < music.out)" = "Pause Play " ]' "stop during a session did not give the player back" kill "$music" "$podcast" 2>/dev/null || true { @@ -1296,6 +1314,8 @@ jobs: pid=$! sleep 1.5 check 'grep -q "^bind .* dictate CTRL+SHIFT+space$" portal.out' "the default chord was not bound through the portal" + # Read by a check() below, inside the string it evals. + # shellcheck disable=SC2034 first=$(grep '^bind ' portal.out | head -1 | cut -d' ' -f2) echo 'activate other' >&6 sleep 1 @@ -1321,8 +1341,12 @@ jobs: check 'grep -q "^register io.github.geiserx.akou$" portal.out' "the helper did not register its app id" check 'grep -q "\"type\":\"session.started\"" helper.err' "Activated started no session" check 'grep -q "\"type\":\"session.ended\",\"id\":\"[^\"]*\",\"reason\":\"release\"" helper.err' "Deactivated did not end the session" + # check() evals this string, so it is single-quoted on purpose. + # shellcheck disable=SC2016 check '[ "$(grep -c "\"type\":\"session.started\"" helper.err)" = 1 ]' "more than one session started" check 'grep -q "^bind .* dictate CTRL+ALT+d$" portal.out' "the rebind did not bind the new chord" + # check() evals this string, so it is single-quoted on purpose. + # shellcheck disable=SC2016 check 'grep -q "^close $first$" portal.out' "the first portal session was not closed on the rebind" check 'grep -q "\"type\":\"rebound\",\"hotkey\":\"Control+Alt+D\"" helper.err' "the rebind to a chord was not answered rebound" check 'grep -q "\"type\":\"rebind.failed\",\"hotkey\":\"RightControl\"" helper.err' "a lone modifier with no readable keyboard was not refused" @@ -1381,6 +1405,8 @@ jobs: shell: bash steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Rust 1.97.1 run: | rustup toolchain install 1.97.1 --profile minimal @@ -1480,6 +1506,8 @@ jobs: timeout-minutes: 60 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false # Under the runner's temp directory: actions/cache refuses a path with `..`, so a models # folder beside the workspace never saved. The runner context is not readable in a job's env. - name: the models and data folders @@ -1515,16 +1543,18 @@ jobs: code=0 docker run --rm -v "$scratch:/data" -v "$MODELS:/models" akou:ci > refused.log 2>&1 || code=$? cat refused.log - [ "$code" = 78 ] && grep -q 'server.behind_proxy' refused.log \ - || { echo "want: exited 78 naming server.behind_proxy; got $code"; exit 1; } + if ! { [ "$code" = 78 ] && grep -q 'server.behind_proxy' refused.log; }; then + echo "want: exited 78 naming server.behind_proxy; got $code"; exit 1 + fi # A folder Docker makes for a bind mount belongs to root; the image runs as uid 1000. locked=$(mktemp -d) sudo chown root:root "$locked" code=0 docker run --rm -e AKOU_BEHIND_PROXY=true -v "$scratch:/data" -v "$locked:/models" akou:ci > locked.log 2>&1 || code=$? cat locked.log - [ "$code" = 77 ] && grep -q '/models is not writable by uid 1000' locked.log \ - || { echo "want: exited 77 naming /models and uid 1000; got $code"; exit 1; } + if ! { [ "$code" = 77 ] && grep -q '/models is not writable by uid 1000' locked.log; }; then + echo "want: exited 77 naming /models and uid 1000; got $code"; exit 1 + fi - name: start the server with only AKOU_BEHIND_PROXY and an empty data folder (SV-P5, SV-P11) run: | mkdir -p "$DATA" @@ -1579,7 +1609,7 @@ jobs: # on a Linux box with no sound server. It prints the transcript, or the step fails. docker run --rm --network host -e AKOU_URL=http://127.0.0.1:8476 -e AKOU_API_KEY \ -v "$work:/work" akou:ci transcribe /work/note.ogg | tee "$work/transcribe.txt" - tr 'A-Z' 'a-z' < "$work/transcribe.txt" | tr -cd 'a-z \n' | grep -q "ask not what your country" + tr '[:upper:]' '[:lower:]' < "$work/transcribe.txt" | tr -cd 'a-z \n' | grep -q "ask not what your country" # SV-T4: Home Assistant's own Wyoming client, the `wyoming` package it pins, against the image. # The container runs with AKOU_WYOMING=true, so a false capability is a bug, not a skip. The # clip is 24 kHz; Home Assistant always sends 16000 Hz, 16-bit, mono, so the step resamples it @@ -1596,7 +1626,7 @@ jobs: "$RUNNER_TEMP/wy/bin/pip" install --require-hashes -r scripts/ci/wyoming/requirements.txt "$RUNNER_TEMP/wy/bin/python" -I scripts/ci/wyoming/probe.py --host 127.0.0.1 --port 10300 --language en --wav "$wy/en16.wav" | tee wyoming.txt head -n1 wyoming.txt | jq -e '.asr[0].name == "akou" and ([.asr[0].models[].name] | index("fast") != null)' - tail -n1 wyoming.txt | tr 'A-Z' 'a-z' | tr -cd 'a-z \n' | grep -q "ask not what your country" + tail -n1 wyoming.txt | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z \n' | grep -q "ask not what your country" - name: the server's log if: always() run: docker logs akou 2>&1 | tail -n 200 || true @@ -1638,7 +1668,7 @@ jobs: test "$(head -n1 asr.srt | tr -d '\r')" = "1" sed -n 2p asr.srt | grep -q -- ' --> ' # Cues hold 42 characters at most, so the phrase may span two: join the cue text first. - tr 'A-Z' 'a-z' < asr.srt | tr -cd 'a-z \n' | tr -s ' \n' ' ' | grep -q "ask not what your country" + tr '[:upper:]' '[:lower:]' < asr.srt | tr -cd 'a-z \n' | tr -s ' \n' ' ' | grep -q "ask not what your country" # SI-8 (docs/research/service-interface.md): `akou serve` natively on macOS arm64, from a source # checkout with no Docker, since Docker on a Mac has no Metal. A Mac mini serving this way is the @@ -1653,6 +1683,8 @@ jobs: timeout-minutes: 30 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: macOS arm64 run: | test "$(uname -m)" = arm64 || { echo "this runner is $(uname -m), not arm64"; exit 1; } @@ -1736,7 +1768,7 @@ jobs: export AKOU_API_KEY AKOU_WEBHOOK_SECRET AKOU_URL=http://127.0.0.1:8476 CALLBACK_HOST=127.0.0.1 bun scripts/server-roundtrip.ts "$work/note.ogg" AKOU_URL=http://127.0.0.1:8476 bun src/main/cli/cli.ts transcribe "$work/note.ogg" | tee "$work/transcribe.txt" - tr 'A-Z' 'a-z' < "$work/transcribe.txt" | tr -cd 'a-z \n' | grep -q "ask not what your country" + tr '[:upper:]' '[:lower:]' < "$work/transcribe.txt" | tr -cd 'a-z \n' | grep -q "ask not what your country" - name: the server's log if: always() run: tail -n 200 "$RUNNER_TEMP/serve.log" || true @@ -1833,6 +1865,8 @@ jobs: VARIANT: ${{ matrix.variant }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: build the ${{ matrix.variant }} image run: docker build --build-arg ACCELERATOR="$VARIANT" -t "akou:$VARIANT" . - name: its llama-server runs @@ -1890,6 +1924,8 @@ jobs: timeout-minutes: 15 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version-file: .bun-version @@ -1907,6 +1943,8 @@ jobs: timeout-minutes: 10 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version-file: .bun-version @@ -1914,13 +1952,48 @@ jobs: with: pattern: junit-* path: junit - - run: bun scripts/trap-coverage.ts $(find junit -name '.junit-*.xml' | sort) + - run: | + mapfile -t files < <(find junit -name '.junit-*.xml' | sort) + bun scripts/trap-coverage.ts "${files[@]}" + + # The workflows themselves (docs/CI-CD.md CI-16), on every run: actionlint with ShellCheck over + # every run block, then zizmor's security audits at medium or above, with every action pinned by + # its commit (.github/zizmor.yml). The three tools are release binaries checked against their + # SHA-256 before they run. + workflows: + runs-on: ubuntu-24.04 + timeout-minutes: 5 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: actionlint 1.7.12, ShellCheck 0.11.0 and zizmor 1.32.0 + run: | + set -euo pipefail + bin="$RUNNER_TEMP/workflow-lint" + mkdir -p "$bin" + fetch() { + curl -fsSL --retry 3 -o "$bin/$1" "$2" + echo "$3 $bin/$1" | sha256sum -c - + } + fetch actionlint.tar.gz https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz 8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8 + fetch shellcheck.tar.gz https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.gz b7af85e41cc99489dcc21d66c6d5f3685138f06d34651e6d34b42ec6d54fe6f6 + fetch zizmor.tar.gz https://github.com/zizmorcore/zizmor/releases/download/v1.32.0/zizmor-x86_64-unknown-linux-gnu.tar.gz bb110cc765eca9cd7efb2e284a956be5974c60027b0970f16397d86208a9957b + tar -xzf "$bin/actionlint.tar.gz" -C "$bin" actionlint + tar -xzf "$bin/shellcheck.tar.gz" -C "$bin" --strip-components=1 shellcheck-v0.11.0/shellcheck + tar -xzf "$bin/zizmor.tar.gz" -C "$bin" zizmor + echo "$bin" >> "$GITHUB_PATH" + - name: actionlint, with ShellCheck over every run block + run: actionlint -color -shellcheck "$RUNNER_TEMP/workflow-lint/shellcheck" + # Offline: the audits read only this tree, so the result never moves with GitHub's API. + - name: zizmor, every action pinned by its commit + run: zizmor --offline --min-severity medium --config .github/zizmor.yml . # The one required check. `if: always()` so it reports even when a leg failed; it fails when any # leg failed or was cancelled, and passes when legs were skipped for a docs-only change. ci-ok: if: always() - needs: [changes, check, ui, helper, capture-linux, capture-windows, server, server-macos, diarize, gpu-image, executor, traps] + needs: [changes, check, ui, helper, capture-linux, capture-windows, server, server-macos, diarize, gpu-image, executor, traps, workflows] runs-on: ubuntu-latest timeout-minutes: 5 steps: diff --git a/.github/workflows/dockerhub-description.yml b/.github/workflows/dockerhub-description.yml index 4a120ecc..ccd2c37d 100644 --- a/.github/workflows/dockerhub-description.yml +++ b/.github/workflows/dockerhub-description.yml @@ -14,6 +14,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false # `enable-url-completion` below rewrites markdown links only. The banner, the screenshot and # the LICENSE link are HTML tags with relative paths, which Docker Hub cannot resolve (the diff --git a/.github/workflows/models.yml b/.github/workflows/models.yml index fdf44444..00c524e5 100644 --- a/.github/workflows/models.yml +++ b/.github/workflows/models.yml @@ -38,6 +38,8 @@ jobs: timeout-minutes: 30 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: 1.4.2 diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 280ab8e4..3025ffcc 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -175,6 +175,8 @@ jobs: run: | if [ -n "$SHIFT" ]; then export BUN_OPTIONS="--preload=$PWD/scripts/ci/shift-clock.ts"; fi if [ -n "$ZONE" ]; then export TZ="$ZONE"; fi + # The ${...} is JavaScript's, for bun to read, not the shell's. + # shellcheck disable=SC2016 bun -e 'console.log(`the clock reads ${new Date().toString()}`)' bun test --reporter=junit --reporter-outfile=.junit-check.xml # The same suite as check's Linux leg, so the zone runs take check's floor. The year-ahead run diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 36ea1f6f..81543040 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -21,6 +21,11 @@ name: release # ELECTROBUN_APPLEIDPASS) and fails when one is missing. Hutch signs the app with the Developer ID # and notarizes it, build-cli.ts does the same for the CLI and build-app.ts for the akou-diarize # archive, and the job checks all three before upload. +# +# Every job that reads a secret (app, image on a push, image-manifest, cask) runs in the `release` +# environment when it can read one (docs/CI-CD.md CI-16). The environment's deployment policy, set +# in the repository settings, decides which refs may reach its secrets; a gate in this file holds +# only for the copy of the file on the ref that runs. on: push: @@ -94,6 +99,7 @@ jobs: - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: ${{ env.BUN_VERSION }} + no-cache: true - run: bun install --frozen-lockfile - name: every version string equals the tag env: @@ -138,6 +144,10 @@ jobs: needs: version runs-on: macos-latest timeout-minutes: 45 + # The signing secrets are read only inside the `release` environment (docs/CI-CD.md CI-16), + # whose deployment policy names the refs that may sign. A pull request's dry run reads none and + # builds ad-hoc, so it runs outside it. + environment: ${{ github.event_name != 'pull_request' && 'release' || '' }} env: # Hutch signs the app with the Developer ID and notarizes it; build-cli.ts does the same for # the CLI, build-app.ts for the akou-diarize archive. A pushed tag (this workflow's only push trigger is v* tags) or a dispatch by hand @@ -201,24 +211,17 @@ jobs: - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: ${{ env.BUN_VERSION }} + no-cache: true - run: bun install --frozen-lockfile - - name: Hutch and the ElectroBun runtime, cached by their pins - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 - with: - path: ~/.hutch - key: hutch-macos-arm64-electrobun-2.0.1-hutch-0.24.3 + # No cache is restored in a job whose build is published (docs/CI-CD.md CI-16): a cache can be + # written by any run on main, so Hutch, the runtime and the recognizer are downloaded and + # checked against their pins here every time. - name: build the app (helper, pages, Workers, ElectroBun through Hutch) run: bun scripts/build-app.ts ${HELPER_FLAG:+"$HELPER_FLAG"} - name: check the built app without opening it run: bun scripts/smoke-app.ts ${HELPER_FLAG:+"$HELPER_FLAG"} - name: the update feed is for this app and this version (docs/CI-CD.md CI-23) run: bun scripts/check-feed.ts --dir dist/release - - name: the recognizer, cached by its pins - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 - with: - path: eval-models - key: recognizer-${{ hashFiles('src/main/asr/models.ts') }} - enableCrossOsArchive: true # Prereleases never wait on a gate (ROADMAP M0), so here the result is recorded, not enforced. # continue-on-error absorbs a failure but not a stall: a slow model download must not push # this release job into its own limit. @@ -345,12 +348,13 @@ jobs: rustup toolchain install "$RUST_VERSION" --profile minimal rustup default "$RUST_VERSION" cargo --version - - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + # This job's builds are never published (see above), so its caches cannot reach a user. + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 # zizmor: ignore[cache-poisoning] with: bun-version: ${{ env.BUN_VERSION }} - run: bun install --frozen-lockfile - name: Hutch and the ElectroBun runtime, cached by their pins - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 # zizmor: ignore[cache-poisoning] with: path: ~/.hutch key: hutch-${{ runner.os }}-x64-electrobun-2.0.1-hutch-0.24.3 @@ -361,7 +365,7 @@ jobs: # The recognizer's files are checked against their pins in src/main/asr/models.ts on every # use, so a stale cache costs a download, never a wrong model. The nightly shares this cache. - name: the recognizer, cached by its pins - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 # zizmor: ignore[cache-poisoning] with: path: eval-models key: recognizer-${{ hashFiles('src/main/asr/models.ts') }} @@ -431,6 +435,7 @@ jobs: - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: ${{ env.BUN_VERSION }} + no-cache: true - run: bun install --frozen-lockfile - name: build the CLI (bun build --compile) run: bun scripts/build-cli.ts @@ -475,6 +480,8 @@ jobs: variant: cuda runs-on: ${{ matrix.runner }} timeout-minutes: 60 + # Docker Hub's secrets only inside the `release` environment, on the push path (CI-16). + environment: ${{ github.event_name == 'push' && 'release' || '' }} env: PUSH: ${{ github.event_name == 'push' && github.ref_type == 'tag' }} PLATFORM: ${{ matrix.platform }} @@ -523,6 +530,7 @@ jobs: if: github.event_name == 'push' && github.ref_type == 'tag' runs-on: ubuntu-24.04 timeout-minutes: 10 + environment: release steps: - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: @@ -577,6 +585,7 @@ jobs: - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: ${{ env.BUN_VERSION }} + no-cache: true - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: pattern: release-* @@ -656,6 +665,7 @@ jobs: if: github.ref_type == 'tag' runs-on: ubuntu-latest timeout-minutes: 10 + environment: release permissions: contents: read steps: @@ -665,6 +675,7 @@ jobs: - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: ${{ env.BUN_VERSION }} + no-cache: true - name: push the cask bump to the tap env: GH_TOKEN: ${{ github.token }} diff --git a/.github/zizmor.yml b/.github/zizmor.yml new file mode 100644 index 00000000..10da7d36 --- /dev/null +++ b/.github/zizmor.yml @@ -0,0 +1,13 @@ +# zizmor's settings for the `workflows` job of ci.yml (docs/CI-CD.md CI-16). Every action is pinned +# by its full commit SHA, the official ones included: an action referenced by a tag or a branch +# fails the job. +rules: + unpinned-uses: + config: + policies: + "*": hash-pin + # How soon Dependabot proposes a new release is the update policy of CI-13, which + # tests/dependabot.test.ts holds, not a property of the workflows this job lints. + dependabot-cooldown: + ignore: + - dependabot.yml diff --git a/docs/CI-CD.md b/docs/CI-CD.md index 1c85e48b..314db99a 100644 --- a/docs/CI-CD.md +++ b/docs/CI-CD.md @@ -44,7 +44,7 @@ changes ─┬─ lint ─────────────────── ``` - `changes` decides which legs a PR needs from the paths it touches. A docs-only PR runs `lint` only. -- `lint` runs Biome, both `tsc`, `cargo fmt --check`, `cargo clippy -D warnings`, the generated-reference drift checks ([TESTING §4.3](TESTING.md#43-contracts-the-three-doors-stay-equal): settings, MCP, the CLI reference of CLI-31, the OpenAPI file of PG-A2, the parity table), `scripts/trap-coverage.ts`, `scripts/ci/clock-lint.ts`, and actionlint and zizmor on `.github/`. +- `lint` runs Biome, both `tsc`, `cargo fmt --check`, `cargo clippy -D warnings`, the generated-reference drift checks ([TESTING §4.3](TESTING.md#43-contracts-the-three-doors-stay-equal): settings, MCP, the CLI reference of CLI-31, the OpenAPI file of PG-A2, the parity table), `scripts/trap-coverage.ts`, `scripts/ci/clock-lint.ts`, and actionlint and zizmor on `.github/` (today a job of its own, `workflows`, CI-16). - `unit` runs `bun test` with the JUnit reporter and the floor check, and `cargo test`. Coverage with its threshold runs on the Linux x64 leg only. The Linux arm64 leg covers the arm64 CLI DESIGN §9 ships, on a runner that is free on public repositories. - `ci-ok` has `needs:` on every job and `if: always()`, and fails when any needed job failed or was cancelled. Skipped is fine; that is the point of `changes`. @@ -99,7 +99,7 @@ CI-3 (squash only) is now part of CI-1. CI-6 (remove the leftover workflow) and | CI-13 | Dependabot, grouped and weekly | P1 | audit (disabled); Minutes groups by ecosystem | `.github/dependabot.yml` for `bun`, `cargo` and `github-actions`: minor and patch grouped in one PR per ecosystem per week, majors alone, each ignore with its reason. Dependabot alerts and security updates turned on. Squash-merged with an explicit subject and body so no trailer is added | has: `.github/dependabot.yml` (ignores `@types/bun`, which moves with `.bun-version`, and `electrobun`, which moves with the Hutch pins), checked by `tests/dependabot.test.ts`; a monthly `pip` entry for `/docs` bumps the docs site's `zensical` pin; alerts and security updates on since 2026-09-25 | | CI-14 | Audits beyond alerts | P2 | alerts miss advisories that `audit` finds | Nightly `bun audit` and `cargo audit`; a high or critical finding fails the night | missing | | CI-15 | CodeQL | P1 | audit (no code scanning) | Code scanning default setup on, first analysis visible under the Security tab | has: default setup on since 2026-09-25 (actions, JavaScript and TypeScript, Rust); the first analysis ran green and opened 13 medium alerts (12 `js/prototype-polluting-assignment` in `src/main/asr/live-worker.ts`, one `js/bad-code-sanitization` in a test), all closed by #42; none open | -| CI-16 | Workflow lint and security scan | P1 | Minutes (actionlint), anarlog (zizmor); public repo | actionlint and zizmor run in `lint` on any `.github/` change; zizmor findings at medium or above fail. zizmor's `unpinned-uses` audit runs with a hash-pin policy for every action, so an action referenced by tag fails; `dangerous-triggers` fails on `pull_request_target`; `artipacked` requires `persist-credentials: false` on every checkout that does not push. One more line in `lint` fails on `secrets.` referenced by any job a `pull_request` event can run. A job may read secrets only when its `if:` limits it to a tag push or `workflow_dispatch`, so a packaging dry run on a pull request builds unsigned. Positive controls: a scratch workflow using `actions/checkout@v4` by tag fails `lint`, and so does a job that reads `secrets.` with a `pull_request` trigger and no such `if:` | partial: SHA pins and no `pull_request_target`; nothing enforces them. The release workflow reads every secret behind `github.event_name == 'push'` or `!= 'pull_request'`, which `tests/release.test.ts` checks | +| CI-16 | Workflow lint and security scan | P1 | Minutes (actionlint), anarlog (zizmor); public repo | actionlint and zizmor run on every `ci.yml` run (the `workflows` job); zizmor findings at medium or above fail. zizmor's `unpinned-uses` audit runs with a hash-pin policy for every action, so an action referenced by tag fails; `dangerous-triggers` fails on `pull_request_target`; `artipacked` requires `persist-credentials: false` on every checkout that does not push. One more line in `lint` fails on `secrets.` referenced by any job a `pull_request` event can run. A job may read secrets only when its `if:` limits it to a tag push or `workflow_dispatch`, so a packaging dry run on a pull request builds unsigned. Every job that reads a secret runs in the `release` environment whenever it can read one (`environment: release`, or an expression that names it behind the same gate as the read), so that with the secrets kept in that environment, its deployment policy decides which refs reach them: tags `v*`, plus `main` while a dispatch dry run must still sign. A workflow pushed on another branch then reads nothing. `dockerhub-description.yml` updates the Hub page on a push to `main` and keeps reading repository secrets. Positive controls: a scratch workflow using `actions/checkout@v4` by tag fails `lint`, and so does a job that reads `secrets.` with a `pull_request` trigger and no such `if:` | has: the `workflows` job of `ci.yml`, under `ci-ok`, runs actionlint 1.7.12 with ShellCheck 0.11.0 and zizmor 1.32.0 (`--min-severity medium`, hash pins for every action in `.github/zizmor.yml`), each a release binary checked against its SHA-256. Every checkout in every workflow sets `persist-credentials: false`, and no job whose build is published restores a cache (`app-desktop`, never published, keeps its caches with an inline ignore). The few ShellCheck notes that are intended carry an inline `disable` with the reason. The release workflow reads every secret behind `github.event_name == 'push'` or `!= 'pull_request'`, and only in jobs that run in the `release` environment; `tests/release.test.ts` checks both (`[WFS-1]`, `[WFS-2]`). The environment and its deployment policy are repository settings: until the secrets move into it, a job with an environment still reads the repository's own | CI-17 (no secrets on PR code) and CI-18 (actions pinned by SHA) are now part of CI-16, which enforces both. diff --git a/docs/TRAPS.md b/docs/TRAPS.md index 7896dd7f..c8749755 100644 --- a/docs/TRAPS.md +++ b/docs/TRAPS.md @@ -176,6 +176,8 @@ Every number here comes from our vocabulary measurements: a synthetic TTS set an - **Compiled Bun binary killed on launch** [spike, oven-sh/bun#39764] (M4). Given `bun build --compile` for the Linux CLI tarball or any macOS CLI binary, Bun must be 1.4.2 or newer: 1.4.0 and 1.4.1 write an invalid ad-hoc Mach-O signature and macOS kills the binary at exec. Bun 1.3.12 does too (measured: exit 137, and `codesign -s - -f` refuses the file). The ElectroBun-bundled Bun 1.4.0 is used only as the app runtime. Test: a version assertion in `scripts/build-cli.ts`, plus `codesign -s - -f` and `codesign --verify --strict` on the output, which fail the build on a bad signature, then `akou --version` from the binary. - **Hutch and ElectroBun version pairing** [spike] (M1). Given ElectroBun 2.0.1, Hutch must be the exact version its npm bootstrap pairs with it, 0.24.3, which the bootstrap downloads and checks against a SHA-256 on first use, with no prompt. It built and ad-hoc signed the app in the release build (the M0 spike built with 0.27.0-canary.10 from source). Test: `scripts/build-app.ts` asserts the bootstrap's pairing before the build and the cached `hutch-release.json` after it. - **Homebrew tap push without a token** [T4.12] (M1). Given a formula-only tap in another repository, the release job must push the cask bump with a fine-scoped token (a GitHub App or a PAT limited to the tap repository) stored as a secret, never the default `GITHUB_TOKEN`, which cannot push to another repository. Test (not written yet): a dry-run bump in CI that fails without the secret. +- **A release secret any branch's workflow can read** [WFS-1] (M1). Given the signing, Docker Hub and tap secrets stored for the whole repository, a gate such as `github.event_name != 'pull_request'` holds only in the copy of `release.yml` on the ref that runs: a workflow pushed on any branch, or a dispatch of `release.yml` on one, can read them. Every job of `release.yml` that reads a secret must run in the `release` environment whenever it can read one, so that with the secrets kept in that environment its deployment policy decides which refs reach them. Test: `[WFS-1]` in `tests/release.test.ts`, every job's secret reads against its `environment:`, with a positive control that drops the environment from `cask` and narrows `app`'s to a push. +- **A workflow change nothing checks** [WFS-2] (M1). Given workflows that pin every action by its commit and keep secrets off pull requests only by habit, an edit that references an action by a tag, puts untrusted text in a run block or adds a `pull_request_target` stays green. A checkout that keeps the job token leaves it in reach of every later step, and a cache restored into a job whose build is published can be written by another run. The `workflows` job of `ci.yml` must run actionlint (with ShellCheck) and zizmor at medium or above, with every action hash-pinned, under `ci-ok`; no checkout keeps the token, since none pushes through it; and no job whose output is published restores a cache, setup-bun's own included. A finding judged harmless carries an inline ignore with its reason. Test: `[WFS-2]` in `tests/release.test.ts`, every checkout of every workflow, the caches of the jobs the release needs or that need it, and the lint job with its pinned tools, each with a positive control. - **Updater replaces the app mid-call** [T4.46] (M1). Given a live call or a running final pass, the updater must defer. Test (not written yet): a fake update while a fake call runs. The app has no updater yet (DK-U1). - **A Worker's first native load stops the main thread** [G2] (M0). Given Windows, a DLL's first load on the machine holds the process's loader lock for as long as it takes, and the first load of a freshly written file (after an install or an update) took 0.1 to 1.7 s on a CI runner. A main thread that calls into the runtime meanwhile waits for the lock: a Worker's first `require("sherpa-onnx-node")` stopped the app's main thread for the whole load in 111 of 120 runs on fresh copies of the files, while a main thread in a tight loop that never called the runtime did not stop. A plain `LoadLibrary` of `onnxruntime.dll` did the same, so neither Bun nor N-API is the cause, and a second process loading the same files took about 10 ms. On Windows the Worker therefore loads the addon in a short child process first (`src/main/asr/native-warm.ts`): the slow load is paid under the child's lock, and the Worker's own load is warm. Test: `tests/native-warm.test.ts` loads the addon from fresh copies in a Worker while the main thread ticks every 1 ms: under 50 ms with the child, and at least one wait of 50 ms or more without it, as the positive control. - **A Worker terminated inside a native load aborts the process** [spike, oven-sh/bun#45252] (M1). Given Bun 1.3.13 through 1.4.4, `Worker.terminate()` while the Worker is inside a native constructor (sherpa-onnx-node's `OfflineRecognizer`, measured) makes the constructor return into a torn-down N-API env, and the whole process aborts: exit 134 with "NAPI FATAL ERROR: Error::Error napi_define_properties" on 1.4.2, "A C++ exception occurred" on 1.4.4, "napi_create_object" on 1.3.13; 1.3.12 survives. A cancelled job, a hang-up, a final pass past its budget or a live Worker's close during a model load took the server or the app down with it (#408); a 280 s load on a starved disk left that window open for minutes. Every native load in `sherpa.ts` therefore runs under `nativeLoad` (`src/main/asr/native-guard.ts`), which counts it on a flag shared with the host, and every host-side terminate goes through `stopWorker`: outside a load the Worker is terminated at once, inside one it parks in JS as soon as the load returns and only then is terminated, while the job itself still ends at once. Remove the guard once the pinned Bun carries oven-sh/bun#45615. Test: `tests/native-guard.test.ts`, the `[bun#45252]` cases, against a fake Worker with a bare terminate as the positive control, and, where Parakeet is on disk (CI's `server-macos` job), a child process that cancels a job 300 ms into the recognizer's load and must outlive it; with `stopWorker` reduced to a bare terminate it exits 134 with the panic above. diff --git a/tests/release.test.ts b/tests/release.test.ts index a60c4aed..9de6edaa 100644 --- a/tests/release.test.ts +++ b/tests/release.test.ts @@ -5,7 +5,7 @@ */ import { describe, expect, test } from "bun:test"; -import { cpSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"; +import { cpSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import config, { @@ -623,6 +623,7 @@ function releaseWorkflow(): { { needs?: string | string[]; if?: string; + environment?: string; permissions?: Record; steps?: { name?: string; @@ -668,6 +669,161 @@ describe("[CI-16] no release checkout leaves the job token for later steps", () }); }); +describe("[WFS-1] a release secret is read only inside the release environment", () => { + type Workflow = ReturnType; + /** The gate of every secret a job reads: `X` in `X && secrets.NAME`, "" when it has none. */ + const gatesOf = (job: Workflow["jobs"][string]): string[] => + [...JSON.stringify(job).matchAll(/\$\{\{\s*(?:([^}]*?)\s*&&\s*)?secrets\.(\w+)/g)] + .filter((m) => m[2] !== "GITHUB_TOKEN") + .map((m) => (m[1] ?? "").trim()); + /** + * Every secret read that can happen outside the `release` environment: the job names no + * environment, or names it behind another gate than the read's own. The environment is what + * limits a secret to the refs its deployment policy allows; a gate in the workflow file holds + * only for the file of the ref that runs. + */ + const outsideRelease = (wf: Workflow): string[] => + Object.entries(wf.jobs).flatMap(([name, job]) => + gatesOf(job) + .filter( + (gate) => + job.environment !== "release" && + job.environment !== `$${"{{"} ${gate} && 'release' || '' }}`, + ) + .map((gate) => `${name}: ${gate || "always"}`), + ); + + test("every job that reads a secret runs in the release environment whenever it can read it", () => { + const wf = releaseWorkflow(); + // The check is not empty: these four jobs read the signing, Docker Hub and tap secrets. + expect( + Object.entries(wf.jobs) + .filter(([, job]) => gatesOf(job).length > 0) + .map(([name]) => name) + .sort(), + ).toEqual(["app", "cask", "image", "image-manifest"]); + expect(outsideRelease(wf)).toEqual([]); + // A pull request's dry run builds unsigned and pushes nothing, so it never needs the + // environment, whose policy would refuse a pull request's ref. + expect(wf.jobs.app?.environment).toBe( + `$${"{{"} github.event_name != 'pull_request' && 'release' || '' }}`, + ); + expect(wf.jobs.image?.environment).toBe( + `$${"{{"} github.event_name == 'push' && 'release' || '' }}`, + ); + }); + + test("positive control: a job without the environment, or behind a looser gate, is caught", () => { + const wf = releaseWorkflow(); + const cask = wf.jobs.cask; + if (cask) delete cask.environment; + expect(outsideRelease(wf)).toEqual(["cask: github.event_name == 'push'"]); + const app = releaseWorkflow(); + // The app reads its secrets on a dispatch too; an environment only on a push leaves that out. + const job = app.jobs.app; + if (job) job.environment = `$${"{{"} github.event_name == 'push' && 'release' || '' }}`; + expect(outsideRelease(app).every((r) => r.startsWith("app: "))).toBe(true); + expect(outsideRelease(app).length).toBeGreaterThan(0); + }); +}); + +describe("[WFS-2] the workflows keep no token, publish nothing from a cache, and are linted", () => { + type Workflow = ReturnType; + const WORKFLOWS = join(ROOT, ".github", "workflows"); + const workflow = (file: string): Workflow => + Bun.YAML.parse(readFileSync(join(WORKFLOWS, file), "utf8")) as never; + const files = (): string[] => + readdirSync(WORKFLOWS).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml")); + + /** Every checkout that leaves the job token in the checkout for the steps after it. */ + const keepingToken = (file: string, wf: Workflow): string[] => + Object.entries(wf.jobs).flatMap(([name, job]) => + (job.steps ?? []) + .filter((s) => s.uses?.startsWith("actions/checkout@")) + .filter((s) => String(s.with?.["persist-credentials"]) !== "false") + .map(() => `${file}: ${name}`), + ); + + /** The release's own job, every job it needs, and every job that needs it: what is published. */ + const publishing = (wf: Workflow): Set => { + const out = new Set(["release"]); + const visit = (name: string) => { + for (const n of [wf.jobs[name]?.needs ?? []].flat()) { + if (out.has(n)) continue; + out.add(n); + visit(n); + } + }; + visit("release"); + for (const [name, job] of Object.entries(wf.jobs)) + if ([job.needs ?? []].flat().includes("release")) out.add(name); + return out; + }; + + /** Every cache a publishing job restores: actions/cache, or setup-bun's own unless no-cache. */ + const cachesInPublishing = (wf: Workflow): string[] => + [...publishing(wf)].flatMap((name) => + (wf.jobs[name]?.steps ?? []) + .filter( + (s) => + /^actions\/cache(\/restore)?@/.test(s.uses ?? "") || + (s.uses?.startsWith("oven-sh/setup-bun@") && String(s.with?.["no-cache"]) !== "true"), + ) + .map((s) => `${name}: ${s.name ?? s.uses}`), + ); + + test("no checkout in any workflow keeps the token: none of them pushes through it", () => { + expect(files().length).toBeGreaterThanOrEqual(7); + expect(files().flatMap((f) => keepingToken(f, workflow(f)))).toEqual([]); + // Positive control: a checkout that keeps it is caught. + const ci = workflow("ci.yml"); + const co = ci.jobs.check?.steps?.find((s) => s.uses?.startsWith("actions/checkout@")); + delete co?.with?.["persist-credentials"]; + expect(keepingToken("ci.yml", ci)).toEqual(["ci.yml: check"]); + }); + + test("a job whose build is published restores no cache; only the unpublished desktop build may", () => { + const wf = releaseWorkflow(); + expect([...publishing(wf)].sort()).toEqual( + ["app", "cask", "cli", "image", "image-manifest", "release", "version"].sort(), + ); + expect(cachesInPublishing(wf)).toEqual([]); + // Positive control: setup-bun's own cache, and an actions/cache step, in the release job. + const steps = wf.jobs.release?.steps ?? []; + const bun = steps.find((s) => s.uses?.startsWith("oven-sh/setup-bun@")); + delete bun?.with?.["no-cache"]; + steps.push({ name: "a cache", uses: "actions/cache@0000000000000000000000000000000000000000" }); + expect(cachesInPublishing(wf)).toEqual([ + "release: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6", + "release: a cache", + ]); + }); + + test("ci.yml lints every workflow with pinned actionlint, ShellCheck and zizmor, under ci-ok", () => { + const ci = workflow("ci.yml"); + const job = ci.jobs.workflows; + const run = (job?.steps ?? []).map((s) => s.run ?? "").join("\n"); + // Each tool is a release binary checked against its SHA-256 before it runs. + for (const tool of [ + "actionlint_1.7.12_", + "shellcheck-v0.11.0", + "zizmor/releases/download/v1.32.0", + ]) + expect(run).toMatch( + new RegExp(`${tool.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\S* [0-9a-f]{64}\\n`), + ); + expect(run).toContain("sha256sum -c -"); + expect(run).toContain('actionlint -color -shellcheck "$RUNNER_TEMP/workflow-lint/shellcheck"'); + expect(run).toContain("zizmor --offline --min-severity medium --config .github/zizmor.yml ."); + expect([ci.jobs["ci-ok"]?.needs].flat()).toContain("workflows"); + // An action referenced by a tag fails: every action, the official ones too, is hash-pinned. + const config = Bun.YAML.parse(readFileSync(join(ROOT, ".github", "zizmor.yml"), "utf8")) as { + rules: { "unpinned-uses": { config: { policies: Record } } }; + }; + expect(config.rules["unpinned-uses"].config.policies).toEqual({ "*": "hash-pin" }); + }); +}); + describe("[CI-19] a release publishes only a commit whose ci-ok is green", () => { const sha = "0".repeat(40); const run = (status: string, conclusion: string | null) => ({