ci-pr.yml

name: CI PR

# PR gate: 3-phase validation. Each phase blocks subsequent phases on
# failure so a busted formatter doesn't pay for a 30-minute build run.
#
#   Phase 1 (Lint):       lint-pr.yml — gst-indent -> clang-tidy
#   Phase 2 (Build/Test): Linux GCC + Clang, macOS Clang, Windows MSVC
#   Phase 3 (Sanitizers): Linux + macOS ASan + UBSan
#
# Within Phase 2 fail-fast is OFF so we get the full matrix's results
# even if one platform breaks first. Phase 3 only runs after Phase 2
# matrix has cleared.

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  # ==========================================================================
  # Phase 1: Lint (hard gates, sequential)
  # ==========================================================================
  lint:
    uses: ./.github/workflows/lint-pr.yml

  # ==========================================================================
  # Phase 2: Build & Test matrix
  # Linux GCC, Linux Clang, macOS Clang, Windows MSVC
  # ==========================================================================
  build:
    name: Build / ${{ matrix.os }} / ${{ matrix.compiler }}
    needs: [lint]
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            compiler: gcc
            cc: gcc
          - os: ubuntu-latest
            compiler: clang
            cc: clang
          - os: macos-latest
            compiler: clang
            cc: clang
          - os: windows-latest
            compiler: msvc
            cc: cl

    steps:
      - uses: actions/checkout@v5

      - name: Install dependencies (Linux)
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y meson ninja-build
          if [ "${{ matrix.compiler }}" = "clang" ]; then
            sudo apt-get install -y clang
          fi

      - name: Install dependencies (macOS)
        if: runner.os == 'macOS'
        run: brew install meson ninja

      - name: Install dependencies (Windows)
        if: runner.os == 'Windows'
        run: pip install meson ninja

      - name: Configure (Linux / macOS)
        if: runner.os != 'Windows'
        run: meson setup builddir
        env:
          CC: ${{ matrix.cc }}

      - name: Configure (Windows / MSVC)
        if: runner.os == 'Windows'
        shell: cmd
        run: |
          call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
          meson setup builddir

      - name: Build (Linux / macOS)
        if: runner.os != 'Windows'
        run: meson compile -C builddir

      - name: Build (Windows / MSVC)
        if: runner.os == 'Windows'
        shell: cmd
        run: |
          call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
          meson compile -C builddir

      - name: Test (Linux / macOS)
        if: runner.os != 'Windows'
        run: meson test -C builddir --print-errorlogs

      - name: Test (Windows / MSVC)
        if: runner.os == 'Windows'
        shell: cmd
        run: |
          call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
          meson test -C builddir --print-errorlogs

      - name: Verify ksuid_explicit_bzero survives optimization
        if: runner.os == 'Linux' && matrix.compiler == 'gcc'
        run: |
          # Issue #2: the DSE-resistant wipe in libksuid/wipe.h must
          # actually emit a call (or equivalent indirect call) at
          # every site in rand_tls.c and chacha20.c. A plain memset
          # would be elided by -O2; explicit_bzero / SecureZeroMemory /
          # the volatile-fn-ptr fallback must NOT be. This step proves
          # the shim's calls survive into the optimised library by
          # grepping the disassembly for either form: a direct call
          # to explicit_bzero@plt (where the static-inline shim got
          # inlined into its caller) or a call to the out-of-line
          # ksuid_explicit_bzero symbol (where the compiler kept
          # the shim as a function). At least four wipe sites exist
          # in source: three in rand_tls.c plus one in chacha20.c, so
          # counting >=4 surviving calls is the correctness floor.
          # Path uses find -type f to skip symlinks AND the
          # libksuid.so.<ver>.p object-archive directory that meson
          # leaves alongside the real .so.
          set -eux
          shared=$(find builddir -maxdepth 1 -type f -name 'libksuid.so.*' \
                   | grep -E 'libksuid\.so\.[0-9]+\.[0-9]+\.[0-9]+$' \
                   | head -1)
          test -n "$shared" || { echo "::error::no versioned libksuid.so found in builddir" >&2; exit 1; }
          n=$(objdump -d "$shared" \
              | grep -cE 'call .*<(explicit_bzero|ksuid_explicit_bzero)' \
              || true)
          echo "wipe call sites in optimised .so: $n"
          # Floor was 4 (3 sites in rand_tls.c + 1 in chacha20.c) before
          # issue #4. The new ksuid_random_thread_state_wipe adds a fifth
          # ksuid_explicit_bzero call to the library's surviving set, so
          # the floor moves to 5.
          if [ "$n" -lt 5 ]; then
            echo "::error::Expected at least 5 surviving wipe calls in libksuid.so.*; found $n. DSE may have eaten the wipes." >&2
            exit 1
          fi

      - name: Verify install lays down license artifacts
        if: runner.os == 'Linux'
        run: |
          DESTDIR="$PWD/staging" meson install -C builddir
          # Architecture-independent paths are stable.
          test -f staging/usr/local/include/libksuid/ksuid.h
          test -f staging/usr/local/include/libksuid/ksuid_version.h
          test -f staging/usr/local/share/doc/libksuid/LICENSE
          test -f staging/usr/local/share/doc/libksuid/LICENSE.MIT
          test -f staging/usr/local/share/doc/libksuid/NOTICE
          # libksuid.pc / libksuid.a / libksuid.so live under
          # ${libdir}, which on Debian-derived distros expands to
          # lib/<triplet>/ (lib/x86_64-linux-gnu, etc.). Search
          # rather than hard-code the path.
          find staging -name 'libksuid.pc' -print | grep -q .
          find staging -name 'libksuid.a'  -print | grep -q .
          find staging -name 'libksuid.so' -print | grep -q .

  # ==========================================================================
  # Phase 2b: Wipe-shim fallback path coverage (issue #2)
  # The default build on every supported matrix lane resolves
  # ksuid_explicit_bzero to a platform primitive (explicit_bzero,
  # SecureZeroMemory, or memset_s). The portable volatile-fn-ptr
  # fallback in libksuid/wipe.h therefore ships *unexercised* unless
  # CI explicitly forces it. This job builds with
  # KSUID_FORCE_VOLATILE_FALLBACK=1, which disables every primitive
  # branch and exercises the fallback. test_wipe asserts the
  # fallback still zeroes the buffers it is given (it does not
  # assert DSE-resistance -- the auto-build disasm gate above is
  # the DSE-resistance witness; this job witnesses fallback
  # correctness on a host that would otherwise never run the path).
  # ==========================================================================
  wipe-fallback:
    name: Wipe shim fallback path coverage
    needs: [lint]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y meson ninja-build

      - name: Configure with KSUID_FORCE_VOLATILE_FALLBACK
        run: |
          meson setup builddir-fb \
            -Dc_args=-DKSUID_FORCE_VOLATILE_FALLBACK=1

      - name: Build
        run: meson compile -C builddir-fb

      - name: Run test_wipe under fallback shim
        run: meson test -C builddir-fb test_wipe --print-errorlogs

      - name: Confirm fallback path actually skipped explicit_bzero
        run: |
          # On the fallback path the shim must NOT emit a call to
          # explicit_bzero@plt anywhere in the optimised library;
          # grepping for any such reference catches a regression
          # where a future contributor adds a primitive without
          # gating on KSUID_FORCE_VOLATILE_FALLBACK.
          set -eux
          shared=$(find builddir-fb -maxdepth 1 -type f \
                   -name 'libksuid.so.*' \
                   | grep -E 'libksuid\.so\.[0-9]+\.[0-9]+\.[0-9]+$' \
                   | head -1)
          if objdump -d "$shared" | grep -qE 'call .*<explicit_bzero@plt>'; then
            echo "::error::Fallback build leaked an explicit_bzero@plt call; KSUID_FORCE_VOLATILE_FALLBACK is not gating the primitive." >&2
            exit 1
          fi

  # ==========================================================================
  # Phase 2c: meson dist round-trip
  # Builds a source tarball, extracts it into a clean tree, and rebuilds
  # the library + tests from the tarball. Catches reproducibility
  # regressions in configure_file templates (R2 from issue #3): if a
  # future contributor adds vcs_tag, __DATE__, or anything build-time-
  # variable to a generated header, this job fails before the PR can
  # land. Runs in parallel to the build matrix.
  # ==========================================================================
  dist:
    name: meson dist round-trip
    needs: [lint]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0      # meson dist needs full git history

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y meson ninja-build

      - name: Build source tarball
        run: |
          meson setup builddir-dist
          meson dist -C builddir-dist --no-tests --formats xztar

      - name: Rebuild from tarball + run tests
        run: |
          set -eux
          tarball=$(ls builddir-dist/meson-dist/libksuid-*.tar.xz)
          extract_root=$(mktemp -d)
          tar -xJf "$tarball" -C "$extract_root"
          src=$(ls -d "$extract_root"/libksuid-*)
          meson setup "$src/build"
          meson compile -C "$src/build"
          meson test -C "$src/build" --print-errorlogs

  # ==========================================================================
  # Phase 3: Sanitizers (ASan + UBSan)
  # Depends on Phase 2 build matrix passing.
  # ==========================================================================
  sanitizers:
    name: Sanitizers / ${{ matrix.os }} / ${{ matrix.compiler }}
    needs: [build]
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            compiler: gcc
            cc: gcc
          - os: ubuntu-latest
            compiler: clang
            cc: clang
          - os: macos-latest
            compiler: clang
            cc: clang

    steps:
      - uses: actions/checkout@v5

      - name: Install dependencies (Linux)
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y meson ninja-build
          if [ "${{ matrix.compiler }}" = "clang" ]; then
            sudo apt-get install -y clang
          fi

      - name: Install dependencies (macOS)
        if: runner.os == 'macOS'
        run: brew install meson ninja

      - name: Configure with sanitizers
        run: >
          meson setup builddir-san
          -Db_sanitize=address,undefined
          -Db_lundef=false
          --buildtype=debug
        env:
          CC: ${{ matrix.cc }}

      - name: Build
        run: meson compile -C builddir-san

      - name: Test
        run: meson test -C builddir-san --print-errorlogs
        env:
          ASAN_OPTIONS: abort_on_error=1:halt_on_error=1
          UBSAN_OPTIONS: abort_on_error=1:halt_on_error=1:print_stacktrace=1