Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
53c0e77
security: pin CI actions to commit SHAs, stop leaking fds to root chi…
claude Nov 7, 2026
6d161ab
ci: run builds, the feth ABI gate and a GUI launch test on macOS 27
claude Nov 7, 2026
ebd6035
build(gui): stamp the app with the SDK it was built with
claude Nov 7, 2026
08b5c04
feat(gui): AppKit-owned main window, testable page model, opt-in Adva…
claude Nov 7, 2026
14c8391
docs: advanced tools roadmap, window/SDK-stamp notes, history row 46
claude Nov 7, 2026
a18e8f3
test/ci: verify backward compatibility of the window and spawn changes
claude Nov 7, 2026
5eb93fb
ci: key the libusb cache by SDK and OS version
claude Nov 7, 2026
a1b552b
ci: build shipping artifacts with Xcode 26, not the newest Xcode
claude Nov 7, 2026
78895aa
ci: keep the macOS 27 GUI job on the newest Xcode
claude Nov 7, 2026
ccceb9e
feat(core): learn a local device's address; never let it take the def…
claude Nov 7, 2026
391c23d
feat(gui): handle local-link devices gracefully, without remembering …
claude Nov 7, 2026
33ca009
chore: translate the remaining Chinese in code, tests, build and CI t…
claude Nov 7, 2026
8b02c8b
fix(core,capi,ci): fixes from a full review; drop dead code
claude Nov 7, 2026
5da4d03
fix(gui): fixes from a full review; drop dead code
claude Nov 7, 2026
189f0ab
docs: AGENTS tree/status/pitfalls 37-42; collapse the AEWP history
claude Nov 7, 2026
a43333b
fix: Swift 6 Sendable capture in HelperClient; wait for the async I/O…
claude Nov 18, 2026
d2a2887
feat: adopt fixes from upstream XiaoMiku01/TetherKit PRs (#6, #19, #2…
claude Nov 18, 2026
4a81d60
style: clang-format the lines this branch changed; treat TEST_SUITE a…
claude Nov 19, 2026
1e35ebf
ci: add CodeQL and Lint workflows; README download button
claude Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .clang-format
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,7 @@ MaxEmptyLinesToKeep: 1
SeparateDefinitionBlocks: Always
SpacesBeforeTrailingComments: 2
QualifierAlignment: Left

# doctest's TEST_SUITE("name") { ... } groups test cases like a namespace; format it as one
# (contents unindented, as everywhere in tests/) instead of as a block that indents its body.
NamespaceMacros: [TEST_SUITE]
12 changes: 12 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Keeps the SHA-pinned GitHub Actions in .github/workflows current.
# Actions are pinned to full commit SHAs (a moved tag cannot swap the code
# that runs with our signing secrets); Dependabot proposes the bumps as PRs.
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
groups:
actions:
patterns: ["*"]
133 changes: 108 additions & 25 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,19 +42,26 @@ jobs:
strategy:
fail-fast: false
matrix:
os: [macos-15, macos-26, macos-15-intel]
# xcode-27 is GitHub's macOS 27 (Golden Gate) image: Apple silicon only.
os: [macos-15, macos-26, macos-15-intel, xcode-27]
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
persist-credentials: false

- name: Toolchain
id: toolchain
run: |
sw_vers; uname -m; cmake --version; c++ --version
# Part of the libusb cache key: runners of the same OS/arch (macos-15,
# macos-26, xcode-27) must not share a libusb built with another SDK.
echo "sdk=$(xcrun --sdk macosx --show-sdk-version)-$(sw_vers -productVersion)" >> "$GITHUB_OUTPUT"

- name: Cache libusb
uses: actions/cache@v4
uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
with:
path: build/libusb-universal
key: libusb-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('scripts/build-libusb.sh') }}
key: libusb-${{ runner.os }}-${{ runner.arch }}-sdk${{ steps.toolchain.outputs.sdk }}-${{ hashFiles('scripts/build-libusb.sh') }}

- name: Build libusb (universal, pinned + hash-verified)
run: ./scripts/build-libusb.sh "$PWD/build/libusb-universal"
Expand Down Expand Up @@ -86,11 +93,21 @@ jobs:
runs-on: macos-26
timeout-minutes: 45
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
persist-credentials: false

- name: Select the newest Xcode
# Newest Xcode *26*, deliberately not 27: a libusb built with the macOS
# 27 SDK segfaults during device enumeration on macOS 15 and 26 (seen in
# CI, see AGENTS.md pitfall 33). Shipping builds stay on the 26 SDK until
# that is understood; the xcode-27 jobs cover building on macOS 27.
- name: Select the newest Xcode 26
run: |
latest="$(ls -d /Applications/Xcode_*.app | sort -V | tail -1)"
# Release bundles only (Xcode_26.x.app), never betas/RCs; `|| true` so a missing
# Xcode 26 reaches the explicit error below instead of aborting silently.
latest="$(ls -d /Applications/Xcode_26*.app 2>/dev/null \
| grep -E '/Xcode_26(\.[0-9]+)*\.app$' | sort -V | tail -1 || true)"
[ -n "${latest}" ] || { echo "::error::no Xcode 26 on this runner"; ls -d /Applications/Xcode_*.app; exit 1; }
sudo xcode-select -s "${latest}"
xcodebuild -version; swift --version

Expand Down Expand Up @@ -126,7 +143,7 @@ jobs:
fi
plutil -p "$app/Contents/Library/LaunchDaemons/com.tetherkitnext.helperd.plist"

- uses: actions/upload-artifact@v4
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: TetherKitNext-dmg
path: |
Expand All @@ -135,20 +152,27 @@ jobs:
if-no-files-found: error

# ----------------------------------------------------------------------------
# Install the DMG on a real Intel Mac and run the CLI from it.
# Install the shipped DMG on the oldest macOS CI offers and run it: the CLI
# from the bundle, then the GUI for a few seconds. Covers backward
# compatibility of the app built on macOS 26 with the newest SDK (both
# architectures; the x86_64 slice only runs on the Intel image).
# ----------------------------------------------------------------------------
intel-smoke:
name: DMG on Intel
name: DMG on ${{ matrix.os }}
needs: package
runs-on: macos-15-intel
strategy:
fail-fast: false
matrix:
os: [macos-15-intel, macos-15]
runs-on: ${{ matrix.os }}
timeout-minutes: 45
steps:
- uses: actions/download-artifact@v4
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: TetherKitNext-dmg
- name: Mount, copy to /Applications, run
run: |
uname -m
sw_vers; uname -m
dmg="$(ls TetherKitNext-*.dmg)"
mnt="$(hdiutil attach -nobrowse -readonly "$dmg" | awk -F'\t' '/\/Volumes\// {print $NF}')"
ditto "$mnt/TetherKitNext.app" /Applications/TetherKitNext.app
Expand All @@ -157,10 +181,11 @@ jobs:
codesign --verify --deep --strict "$app"
"$app/Contents/MacOS/tetherkitnext-cli" --version
"$app/Contents/MacOS/tetherkitnext-cli" --list
# Launch the GUI briefly: proves the x86_64 Swift slice + dylibs load.
"$app/Contents/MacOS/TetherKitNext" & pid=$!
# Launch the GUI briefly: proves this architecture's Swift slice and
# dylibs load, and that nothing at launch needs a newer macOS.
"$app/Contents/MacOS/TetherKitNext" > gui.log 2>&1 & pid=$!
sleep 8
kill -0 "$pid" || { echo "::error::GUI exited early on Intel"; exit 1; }
kill -0 "$pid" || { echo "::error::GUI exited early on $(sw_vers -productVersion) $(uname -m)"; cat gui.log; exit 1; }
kill "$pid"

# ----------------------------------------------------------------------------
Expand All @@ -180,7 +205,7 @@ jobs:
timeout-minutes: 15
continue-on-error: true
steps:
- uses: actions/download-artifact@v4
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: TetherKitNext-dmg
path: built
Expand Down Expand Up @@ -212,12 +237,60 @@ jobs:
for dmg in built/*.dmg; do shoot "$dmg" "ci-build"; done
for dmg in released/*.dmg; do [ -f "$dmg" ] && shoot "$dmg" "published-release"; done
ls -l shots
- uses: actions/upload-artifact@v4
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: dmg-window-${{ matrix.os }}
path: shots/*.png
if-no-files-found: warn

# ----------------------------------------------------------------------------
# macOS 27 (Golden Gate) with the Xcode 27 toolchain: the GUI builds with the
# macOS 27 SDK (Swift 6 strict concurrency, the @State macro), its unit tests
# pass, and the bundled app launches and stays up. Together with the
# native + feth ABI jobs on xcode-27 this is the automated part of the
# Golden Gate support statement (docs/MACOS-27.md lists what still needs a
# real device).
# ----------------------------------------------------------------------------
gui-macos-27:
name: GUI · macOS 27 (Xcode 27)
runs-on: xcode-27
timeout-minutes: 45
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
persist-credentials: false
- name: Toolchain
run: |
sw_vers; uname -m
# This job is the macOS 27 / Xcode 27 check: newest Xcode on purpose.
latest="$(ls -d /Applications/Xcode_*.app | sort -V | tail -1)"
sudo xcode-select -s "${latest}"
xcodebuild -version; swift --version
- name: Build C++ (native arch)
run: |
./scripts/build-libusb.sh "$PWD/build/libusb-universal"
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DLibUSB_ROOT="$PWD/build/libusb-universal" -DTETHERKITNEXT_BUILD_BENCHMARKS=OFF \
-DTETHERKITNEXT_WARNINGS_AS_ERRORS=ON
cmake --build build -j"$(sysctl -n hw.ncpu)"
- name: Build app bundle (ad-hoc signed)
run: ./gui/Scripts/build-gui.sh
- name: Swift unit tests
run: TETHERKITNEXT_LIB_DIR="$PWD/build/lib" swift test --package-path gui
- name: Launch smoke test
run: |
app=dist/TetherKitNext.app
otool -l "$app/Contents/MacOS/TetherKitNext" | grep -A4 LC_BUILD_VERSION
"$app/Contents/MacOS/TetherKitNext" > launch.log 2>&1 &
pid=$!
sleep 15
if ! kill -0 "$pid" 2>/dev/null; then
echo "::error::TetherKitNext exited within 15 s of launch on macOS 27"
cat launch.log; exit 1
fi
kill "$pid"; wait "$pid" 2>/dev/null || true
echo "✓ app launched and stayed up on $(sw_vers -productVersion)"

# ----------------------------------------------------------------------------
# ThreadSanitizer: the lock-free rings and the park/wake handshake.
# ----------------------------------------------------------------------------
Expand All @@ -226,7 +299,9 @@ jobs:
runs-on: macos-26
timeout-minutes: 45
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
persist-credentials: false
- name: Build libusb
run: ./scripts/build-libusb.sh "$PWD/build-tsan/libusb-universal"
- name: Configure & build
Expand All @@ -250,9 +325,12 @@ jobs:
strategy:
fail-fast: false
matrix:
os: [macos-15, macos-26, macos-15-intel]
# xcode-27 is GitHub's macOS 27 (Golden Gate) image: Apple silicon only.
os: [macos-15, macos-26, macos-15-intel, xcode-27]
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
persist-credentials: false
- name: Build
run: |
./scripts/build-libusb.sh "$PWD/build/libusb-universal"
Expand All @@ -262,15 +340,18 @@ jobs:
- name: Disable feth hardware checksum offload
run: sudo sysctl -w net.link.fake.hwcsum=0
- name: Run feth/BPF cases as root
# bash (not the default `bash -e`) adds -o pipefail, so a failing ctest is not
# masked by `| tee`; without it the gate below could pass with red root tests.
shell: bash
run: |
# Pin the log language: the gate greps for a message text.
sudo env TETHERKITNEXT_ROOT_TESTS=1 TETHERKITNEXT_LANG=en \
ctest --test-dir build -V -R 'net\.' 2>&1 | tee abi.log
# Skip notice is hard-coded in tests/test_net_link.cc.
if grep -q "需要 root 且需设置" abi.log; then
if grep -q "needs root and TETHERKITNEXT_ROOT_TESTS=1" abi.log; then
echo "::error::feth cases were skipped; the ABI check did not run"; exit 1
fi
# kNetCreated. (The previous gate grepped for "创建了 feth", a string
# kNetCreated. (The previous gate grepped for a Chinese message ("feth created"), a string
# that stopped existing when log messages were localized — it could
# never pass.)
if ! grep -q "created virtual interface feth" abi.log; then
Expand All @@ -294,7 +375,9 @@ jobs:
permissions:
contents: write
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
persist-credentials: false

- name: Validate tag
env:
Expand All @@ -306,7 +389,7 @@ jobs:
[ "${BASH_REMATCH[1]}" = "$version" ] \
|| { echo "::error::tag ${TAG} does not match CMakeLists VERSION ${version}"; exit 1; }

- uses: actions/download-artifact@v4
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: TetherKitNext-dmg
path: artifact
Expand Down
101 changes: 101 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# CodeQL: static security analysis of the C++ driver/C ABI, the Swift app and
# root daemon, and these GitHub Actions workflows. Results appear under
# Security › Code scanning.
#
# Toolchain: macOS 26 + Xcode 26 on purpose. CodeQL cannot trace builds on
# macOS 27 / Xcode 27 or analyze Swift 6.4 (GitHub changelog 2026-10-19,
# "CodeQL changes for macOS 27, Xcode 27 and Swift 6.4"); Xcode 26 ships
# Swift 6.3, which CodeQL supports.
#
# libusb is built *before* `init`, so CodeQL traces only our own code.

name: CodeQL

on:
push:
branches: [main]
pull_request:
schedule:
- cron: "27 3 * * 1" # weekly, so new queries also run on unchanged code
workflow_dispatch:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
analyze:
name: CodeQL · ${{ matrix.language }}
runs-on: ${{ matrix.runner }}
timeout-minutes: 60
permissions:
contents: read
actions: read
security-events: write
strategy:
fail-fast: false
matrix:
include:
- language: c-cpp
runner: macos-26
build-mode: manual
- language: swift
runner: macos-26
build-mode: manual
- language: actions
runner: ubuntu-latest
build-mode: none
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
persist-credentials: false

- name: Select Xcode 26
if: runner.os == 'macOS'
run: |
latest="$(ls -d /Applications/Xcode_26*.app 2>/dev/null \
| grep -E '/Xcode_26(\.[0-9]+)*\.app$' | sort -V | tail -1 || true)"
[ -n "${latest}" ] || { echo "::error::no Xcode 26 on this runner"; ls -d /Applications/Xcode_*.app; exit 1; }
sudo xcode-select -s "${latest}"
xcodebuild -version; swift --version

- name: Build libusb (not analyzed)
if: runner.os == 'macOS'
run: ./scripts/build-libusb.sh "$PWD/build/libusb-universal"

# The Swift package links libtetherkitnext, so build the C++ side first,
# outside the trace (the c-cpp job analyzes it).
- name: Build the C++ library for the Swift package (not analyzed)
if: matrix.language == 'swift'
run: |
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug \
-DLibUSB_ROOT="$PWD/build/libusb-universal" \
-DTETHERKITNEXT_BUILD_TESTS=OFF -DTETHERKITNEXT_BUILD_BENCHMARKS=OFF
cmake --build build -j"$(sysctl -n hw.ncpu)"

- name: Initialize CodeQL
uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
languages: ${{ matrix.language }}
build-mode: ${{ matrix.build-mode }}
queries: security-extended

- name: Build C++ (traced)
if: matrix.language == 'c-cpp'
run: |
cmake -S . -B build-codeql -DCMAKE_BUILD_TYPE=Debug \
-DLibUSB_ROOT="$PWD/build/libusb-universal" \
-DTETHERKITNEXT_BUILD_TESTS=OFF -DTETHERKITNEXT_BUILD_BENCHMARKS=OFF
cmake --build build-codeql -j"$(sysctl -n hw.ncpu)"

- name: Build Swift (traced)
if: matrix.language == 'swift'
run: TETHERKITNEXT_LIB_DIR="$PWD/build/lib" swift build --package-path gui

- name: Analyze
uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
category: "/language:${{ matrix.language }}"
Loading
Loading