AlfaMacDriver

AlfaMacDriver is an independent, open-source macOS DriverKit implementation for MediaTek MT7921AU / MT7961 USB Wi-Fi and Bluetooth hardware.

It combines a native SwiftUI application, separate USBDriverKit services, versioned IOUserClient contracts, an Ethernet-style NetworkingDriverKit data path, and an application-owned Bluetooth stack. The current baseline is hardware-validated for WPA2-Personal networking, DHCP and data transfer, mouse and keyboard input, device bonding, and A2DP/SBC audio.

Warning

This is development software, not a production Wi-Fi driver. The current locally signed ad-hoc test build requires a dedicated test Mac, Reduced Security, and System Integrity Protection (SIP) to be disabled temporarily. Do not use this procedure on a primary or production computer.

Engineering highlights

• Wi-Fi: firmware initialization, passive discovery, monitor capture, authorized injection, WPA2-Personal association, DHCP, and bidirectional data.
• Bluetooth: Classic and Low Energy discovery, pairing, encrypted bonding, HID/HOGP input, and A2DP audio with the SBC codec.
• Architecture: Swift 6 and SwiftUI host application, C++20 portable driver core, separate Wi-Fi and Bluetooth DEXTs, and bounded versioned user-client ABIs.
• Quality: portable unit and contract tests, AddressSanitizer, UndefinedBehaviorSanitizer, ThreadSanitizer, strict Swift formatting, static analysis, and CI.
• Publication discipline: pinned upstream provenance, explicit mixed-license boundaries, firmware separation, privacy checks, and reproducible artifact verification.

Project status

Item	Status
Current source release candidate	0.7.0 (126)
Hardware-verified baseline	0.7.0 (126), local ad-hoc build
Driver model	DriverKit / USBDriverKit / NetworkingDriverKit system extension
Target chipset	MediaTek MT7921AU / MT7961
USB identity	VID 0x0E8D, PID 0x7961, interface 3
Logical interface name	wlan1
Capture link type	DLT_IEEE802_11_RADIO (127)
Ethernet-style enX source path	Hardware-validated for WPA2, DHCP, and data
User-space Bluetooth	Hardware-validated for HID and A2DP/SBC
Native AirPort / CoreWLAN interface	Not available
Distribution signing and notarization	Not available
Intended audience	Driver developers, researchers, and authorized lab users

The current source includes a graphical network scanner, monitor mode, Radiotap capture, explicitly authorized raw 802.11 frame injection, a WPA2-Personal station path, an Ethernet-style NetworkingDriverKit data path, and an application-owned Bluetooth stack for mouse, keyboard, and A2DP/SBC audio. It does not register as a native AirPort/CoreWLAN interface or as the system Bluetooth controller.

The name wlan1 is the project-level monitor interface used by the CLI and integrations. The validated station path uses an Ethernet-style enX interface; it does not become an AirPort/CoreWLAN interface.

Detailed implementation and hardware-validation notes are maintained in Documentation/CURRENT_STATUS.md. Release-candidate changes are summarized in Documentation/RELEASE_NOTES_0.7.0.md. The limitations and isolated-lab procedure for any downloadable ad-hoc build are documented in Documentation/DEVELOPER_PREVIEW.md.

Developer Preview

Version 0.7.0 (126) is available as an optional, locally ad-hoc-signed Developer Preview for isolated research Macs:

• Release page and downloads
• Installation, verification, and risk disclosure
• Release notes

The validated application archive has this SHA-256 digest:

712fbed00bdb0c73ed3e03e1182087e5c3a471bb6a5354dc7a0b54df563dec7e

The preview is not Apple-notarized and is expected to be rejected by Gatekeeper under normal security settings. It is not a normal end-user installation.

Network scanner application

The host application provides a native SwiftUI dashboard for passive discovery:

• SSID and BSSID presentation, including hidden and non-UTF-8 SSIDs.
• Security classification for open, WEP, WPA, WPA2, WPA3, OWE, and mixed networks.
• Channel, band, RSSI, signal quality, observation count, and frame-source details.
• Search and band filtering.
• DriverKit extension installation and removal controls.
• Read-only diagnostics in explicitly enabled development builds.

Opening the application refreshes extension status and starts a cancelable passive discovery. It does not initialize firmware, associate with a network, enable persistent monitor mode, or start injection automatically. The scanner requires an initialized radio, temporarily enables monitor mode only when necessary, visits the driver-configured channel allowlist, restores the original channel, and disables monitor mode only when the scanner enabled it.

The application includes a capability-gated Connect sheet with an English secure-password workflow and device-only Keychain support. Source release 0.7.0/126 implements and hardware-validates the bounded managed-connection transaction. The staged connection plan is documented in Documentation/STATION_MODE_PLAN.md.

Implemented capabilities

• USBDriverKit matching and lifecycle management for the target USB interface.
• Chip identity, revision, and endpoint-contract validation.
• Bounded ROM Patch and WM RAM firmware loading.
• Running-firmware adoption after a DriverKit extension upgrade.
• DMA, UDMA, WFSYS, and radio initialization.
• MCU responses through USB endpoint 0x84.
• Monitor frames and TX-status events through USB endpoint 0x85.
• Raw transmit queues through USB endpoints 0x04 through 0x07.
• Monitor-mode enable and disable operations.
• Country and channel allowlists.
• Channel switching and fresh-result passive scanning.
• Native SwiftUI passive network scanner with search, filtering, summaries, and network inspection.
• Radiotap output in PCAPNG and classic PCAP containers.
• USB-completion timestamps in capture output.
• Explicitly authorized raw-frame injection through TXWI.
• Fresh TX-status matching by packet ID and sequence, including ACK results.
• Bounded RX-transfer resubmission and disconnect handling.
• Wireshark Extcap, Kismet datasource, and Scapy integration paths.
• Versioned and size-checked IOUserClient messages.
• Defensive selector, scalar, descriptor, and output-length validation.
• Versioned station-capability query through selector 28.
• Versioned managed-station selectors 29 through 35 for connection, status, disconnect, EAPOL exchange, temporal-key installation, and secure-port activation.
• Shared driver and application connection-state values.
• Portable Probe Request, open-authentication, association, reassociation response, deauthentication, and disassociation frame handling.
• Bounded portable station-management state machine for optional probing, authentication, association, retry limits, cancellation, explicit disconnect, remote disconnect, and beacon loss.
• Versioned and bounded station start-request/status contract with strict 2.4 GHz WPA2-Personal CCMP target validation and no credential fields.
• Portable station-management session with abstract frame transmission, transport-failure handling, counters, cancellation, and shutdown ownership.
• Internal MT7921 station-management transmitter using the existing TXWI and USB data sink with separate station-channel authorization.
• Instantiated non-blocking station runtime and bounded 32-frame receive handoff on a dedicated serial DriverKit queue.
• Rollback-safe portable station firmware transaction with explicit BSS, peer, association, cleanup, recovery, and shutdown ownership.
• Bounded generation-tagged station phase-timer policy with cancellation and overflow-safe deadlines.
• Fresh per-attempt station TX-status receipts bound to Packet ID and the pre-submit status sequence.
• Strict WPA2-Personal CCMP RSN information validation for association-request construction.
• Exact MT7921 BSS, STA_REC, nested WTBL, association, key, and secure-port firmware command encoding.
• DriverKit monotonic station deadlines and rollback-safe orchestration.
• WPA2-Personal PMK/PTK derivation, strict EAPOL four-way-handshake processing, replay and MIC validation, GTK unwrap, firmware key lifecycle, and secure key cleanup.
• Bidirectional 802.11/LLC/SNAP/Ethernet conversion with peer WCID selection, QoS mapping, and hardware CCMP offload metadata.
• Main USB DEXT NetworkingDriverKit packet pool and four bounded packet queues, with link state held inactive until the secure-port gate opens.
• Capability-gated graphical connection sheet and device-only Keychain credential storage.
• Application-owned WPA2 transaction with secure nonce generation, strict EAPOL validation, protected message 4 transmission, progress, cancellation, and disconnect handling.
• Independent experimental NetworkingDriverKit DEXT target with four bounded packet queues, serialized TX callbacks, synthetic TX-to-RX frame copying, sleep/wake handling, and active-link lifecycle reporting.
• Isolated opt-in runtime host that embeds only the experimental Ethernet DEXT and never submits an activation request at launch.
• Portable synthetic Ethernet lifecycle, frame-copy, and bounded-loopback tests, plus a read-only runtime verifier.
• NetworkingDriverKit feasibility checks for arm64 and x86_64.
• Separate Bluetooth USB DEXT for the adapter's Bluetooth interface.
• Application-owned HCI, L2CAP, SDP, SMP, GATT, Classic HID, HOGP, AVDTP, and A2DP paths.
• Keychain-backed Bluetooth bonding and reconnect without repeated pairing.
• Mouse and keyboard delivery through macOS accessibility APIs.
• System-audio capture and A2DP/SBC streaming to a connected headset.

Not implemented

• AirPort or CoreWLAN registration.
• Native macOS system Bluetooth-controller registration.
• Access-point mode.
• Bluetooth SCO or ISO transport and codecs other than the implemented A2DP/SBC path.
• DFS-channel injection.
• 6 GHz injection.
• Production distribution through Apple signing and notarization.
• Production-grade long-duration or multi-client qualification.
• Complete calibration and regulatory validation for every region and device.

Architecture

MT7921AU / MT7961 USB adapter
        |
        +---- Wi-Fi USB interface ---- AlfaUsbDriver DEXT
        |                              +---- monitor and capture
        |                              +---- station data path
        |                              +---- authorized injection
        |
        +---- Bluetooth USB interface - AlfaBluetoothDriver DEXT
                                       +---- HCI and L2CAP
                                       +---- HID and HOGP
                                       +---- A2DP/SBC audio
        |
        v
AlfaMacDriver application / CLI and versioned IOUserClient ABIs

See Documentation/ARCHITECTURE.md for the component and data-flow design.

Requirements

• A dedicated Apple-silicon test Mac is strongly recommended.
• A recent version of macOS and Xcode with DriverKit and USBDriverKit SDKs.
• Administrator access to the test Mac.
• The target MT7921AU / MT7961 USB adapter.
• Firmware files obtained independently from an authorized source.
• An Apple Developer signing configuration for normal system-extension use, or an explicitly isolated local ad-hoc test setup.

Firmware binaries are excluded from Git source history. See Documentation/FIRMWARE.md for the pinned source, expected names, integrity hashes, and provenance notes.

Security preparation for the current local test build

Caution

The current ad-hoc development build requires SIP to be disabled temporarily. Disabling SIP removes important macOS protections and allows unauthorized code to run more easily. Use a dedicated test Mac, disconnect sensitive storage and accounts, and restore all security settings immediately after testing.

This requirement applies to the repository's current local ad-hoc testing workflow. It is not presented as a requirement for a future correctly signed and notarized release.

1. Back up and isolate the test Mac

Before changing security settings:

• Back up any important data.
• Do not use a work-managed or production Mac.
• Sign out of unnecessary accounts and remove sensitive data.
• Disconnect unrelated external storage and USB devices.

2. Enter macOS Recovery on Apple silicon

1. Shut down the Mac completely.
2. Press and hold the power button.
3. Release it when Loading startup options appears.
4. Select Options, then select Continue.
5. Authenticate with an administrator account when requested.

3. Select Reduced Security

1. In Recovery, open Utilities > Startup Security Utility.
2. Select the startup system and unlock it if required.
3. Select Security Policy.
4. Select Reduced Security.
5. Confirm the change with an administrator account.

Only change the options required by the isolated test environment. DriverKit is not a legacy kernel extension, so do not enable unrelated kernel-extension options unless another component in your test environment specifically needs them.

4. Disable System Integrity Protection

While still in Recovery:

1. Open Utilities > Terminal.
2. Run:

csrutil disable

3. Restart the Mac.
4. After macOS starts, verify the state:

csrutil status

The output must report that System Integrity Protection is disabled before the current local ad-hoc activation workflow is attempted.

5. Enable system-extension developer mode

In a normal Terminal session after restarting:

sudo systemextensionsctl developer on

Developer mode relaxes the normal application-location check for development. It does not replace the required entitlements, signatures, user approval, or other DriverKit checks.

6. Restore macOS security after testing

Do not leave the test Mac in this state.

First disable system-extension developer mode:

sudo systemextensionsctl developer off

Then restart into Recovery again, open Utilities > Terminal, and run:

csrutil enable

In Startup Security Utility, restore Full Security, then restart macOS. Verify the final SIP state:

csrutil status

The output should report that System Integrity Protection is enabled.

Apple references:

• Debugging and testing system extensions
• Disabling and enabling System Integrity Protection
• Change security settings on an Apple-silicon Mac

Building

List schemes and destinations

xcodebuild \
  -list \
  -project AlfaMacDriver.xcodeproj

xcodebuild \
  -showdestinations \
  -project AlfaMacDriver.xcodeproj \
  -scheme AlfaUsbDriver

Unsigned Release build of the DriverKit extension

Use the DriverKit destination shown by xcodebuild -showdestinations. On an Apple-silicon development Mac, a typical command is:

xcodebuild \
  -project AlfaMacDriver.xcodeproj \
  -scheme AlfaUsbDriver \
  -configuration Release \
  -destination 'platform=macOS,arch=arm64,variant=DriverKit,name=My Mac' \
  -derivedDataPath build/DerivedData \
  CODE_SIGNING_ALLOWED=NO \
  CODE_SIGNING_REQUIRED=NO \
  clean build

This command verifies compilation and linking only. An unsigned system extension cannot be activated as a normal distributable DriverKit product.

Unsigned Release build of the host application

xcodebuild \
  -project AlfaMacDriver.xcodeproj \
  -scheme AlfaMacDriver \
  -configuration Release \
  -destination 'platform=macOS,arch=arm64,name=My Mac' \
  -derivedDataPath build/DerivedData \
  CODE_SIGNING_ALLOWED=NO \
  CODE_SIGNING_REQUIRED=NO \
  build

Portable CLI and test build

make alfa-wlan
make test
make thread-sanitize

The portable tests exercise parsing, control contracts, capture formats, injection authorization, TX-status handling, station-management frames, the bounded station-management state machine, the portable session and operation wire contract, the internal transmitter and serialized runtime, and integrations without opening a real DriverKit connection or transmitting through hardware.

The public NetworkingDriverKit SDK boundary and portable synthetic model can be checked independently:

make networking-feasibility
make test
make sanitize

The separate unsigned experimental DEXT can be built with the AlfaEthernetProbe scheme. It is not embedded in the application and must not be installed or activated until the runtime Phase 1 prerequisites are met. See Experiments/NetworkingDriverKitProbe/README.md.

Signing verification

A signed build must pass the repository verification gate before installation or activation:

make verify-signed-app \
  SIGNED_APP=/path/to/AlfaMacDriver.app

For an isolated local ad-hoc build:

make verify-local-adhoc-app \
  SIGNED_APP=/path/to/AlfaMacDriver.app

The verification commands inspect application and extension signatures, identities, entitlements, provisioning expectations, bundle identifiers, and USB matching declarations. They do not install or activate the extension.

Installation and activation

The bundled application is a passive network scanner and DriverKit extension manager. It also exposes the development CLI through its main executable.

A typical local development workflow is:

1. Complete the isolated security preparation above.
2. Build an appropriately signed or local ad-hoc application and extension.
3. Run the repository's signing verifier.
4. Copy AlfaMacDriver.app to /Applications when required by the selected activation mode.
5. Launch the application and request installation of the system extension.
6. Approve the extension in macOS System Settings if macOS requests approval.
7. Restart when macOS requests it.
8. Confirm that the extension is activated before connecting to the real IOUserClient interface.

The installed executable is expected at:

/Applications/AlfaMacDriver.app/Contents/MacOS/AlfaMacDriver

For convenience:

export ALFA_WLAN_BIN="/Applications/AlfaMacDriver.app/Contents/MacOS/AlfaMacDriver"
"$ALFA_WLAN_BIN" --help

Do not present the current ad-hoc build as a normal, trusted, or production release. A maintainer-approved Developer Preview must carry the warnings and isolated-lab procedure in Documentation/DEVELOPER_PREVIEW.md. A trusted public binary release still requires appropriate Apple entitlements, Developer ID signing, provisioning where applicable, notarization, and independent release testing.

Safe operational workflow

1. Read diagnostics first

"$ALFA_WLAN_BIN" diagnostics --json
"$ALFA_WLAN_BIN" station-capabilities --json

Do not begin firmware or DMA initialization unless the diagnostic output reports:

safe_for_dma_configuration: true

The driver repeats the safety check internally before the first hardware write. The CLI output is not a substitute for that internal guard.

The station-capability response is read-only. Source release 0.7.0/126 reports the transaction as implemented. The active DEXT must still match the candidate build before hardware results are attributed to it.

2. Load firmware

"$ALFA_WLAN_BIN" firmware-load \
  --patch /path/to/WIFI_MT7961_patch_mcu_1_2_hdr.bin \
  --ram /path/to/WIFI_RAM_CODE_MT7961_1.bin

When upgrading only the extension while compatible firmware remains active:

"$ALFA_WLAN_BIN" firmware-adopt

3. Initialize the radio policy

Use a valid locally administered MAC address and a country/channel policy that matches the physical location and applicable regulations:

"$ALFA_WLAN_BIN" radio-init \
  --mac 02:11:22:33:44:55 \
  --country DE \
  --channels 2:1,2:6,2:11,5:36 \
  --inject-channels 2:1,2:6,2:11,5:36 \
  --initial 2:6

Injection is permitted only on channels explicitly listed by --inject-channels.

4. Enable monitor mode and scan passively

"$ALFA_WLAN_BIN" monitor-on

"$ALFA_WLAN_BIN" scan \
  --channels 2:1,2:6,2:11,5:36 \
  --dwell-ms 250

5. Capture

PCAPNG:

"$ALFA_WLAN_BIN" capture --output capture.pcapng

Classic PCAP:

"$ALFA_WLAN_BIN" capture \
  --output capture.pcap \
  --format pcap

The output uses Radiotap with DLT_IEEE802_11_RADIO (127).

6. Authorized injection only

"$ALFA_WLAN_BIN" inject \
  --file authorized-frame.bin \
  --channel 2:6 \
  --mode cck \
  --rate 0 \
  --pid 1 \
  --wait-status-ms 500 \
  --authorized

USB submission alone is not treated as wireless success. The command waits for a fresh hardware TX status when requested.

Tool integrations

Tool	Integration
Wireshark	Extcap adapter and Radiotap capture
Kismet	External datasource for logical wlan1
Scapy	SuperSocket receive and authorized injection path
tcpdump	Reads generated Radiotap PCAPNG/PCAP captures
Aircrack-ng-compatible readers	Classic PCAP output with link type 127

See Documentation/TOOL_INTEGRATION.md for setup and command examples.

Testing and verification

The repository contains portable tests for:

• Firmware parsing and bounded staging.
• USB endpoint semantics.
• Driver-service and selector-dispatch contracts.
• IOUserClient version, selector, scalar, and descriptor validation.
• Radio policy and channel authorization.
• Monitor and passive-scan behavior.
• Network presentation, filtering, security labels, and summary behavior.
• Station-capability wire decoding and shared state values.
• Portable station-management frame construction and parsing.
• Bounded station-management transitions, retry limits, malformed-response handling, cancellation, disconnect, and beacon-loss recovery.
• Station firmware rollback ordering, timer generations and deadline bounds, and stale station TX-status rejection.
• Synthetic Ethernet lifecycle, bounded buffering, frame validation, and deterministic portable loopback.
• Experimental Ethernet DEXT isolation, explicit matching, and inactive-link contracts.
• NetworkingDriverKit public-API compilation for DriverKit arm64 and x86_64.
• Radiotap, PCAPNG, and PCAP output.
• Capture timestamps.
• Injection requests and fresh TX-status matching.
• Wireshark, Kismet, and Scapy adapters.
• Signed-application verification rules.
• AddressSanitizer and UndefinedBehaviorSanitizer paths.

Run the portable suite with:

make test
make sanitize
make verify-public-tree
make networking-feasibility

Passing portable tests does not by itself prove safe behavior on real hardware. Review the hardware test plan before using a physical adapter:

• Documentation/HARDWARE_TEST_PLAN.md
• Documentation/SAFETY_AUDIT.md

Repository layout

App/                 Host application and CLI entry point
Driver/              Portable driver core and protocol logic
Extension/           DriverKit / USBDriverKit integration
Tools/               CLI, verification, packaging, and tool adapters
Tests/               Unit, contract, integration, and sanitizer tests
Documentation/       Architecture, safety, firmware, status, and release notes
AlfaMacDriver.xcodeproj/
Makefile

Security policy

Do not publish sensitive diagnostics, device identifiers, signing material, provisioning profiles, firmware obtained under restricted terms, packet captures, or credentials in an issue.

Report suspected vulnerabilities according to SECURITY.md.

Responsible and lawful use

This project includes monitor-mode capture and raw-frame injection capabilities. Those capabilities are intended only for:

• Hardware and driver development.
• Controlled laboratory testing.
• Defensive research.
• Networks, devices, and radio environments that you own or for which you have explicit written authorization.

Do not use this software to intercept private communications, gain unauthorized access, disrupt services, evade access controls, interfere with other users, violate spectrum regulations, or perform any activity prohibited by applicable law or policy.

You are solely responsible for determining whether your intended use is legal, authorized, safe, and compliant with local radio regulations. Authorization to use a network does not automatically authorize packet injection, interference, or collection of third-party traffic.

Disclaimer

This software is experimental and is provided as is, without warranties or guarantees of correctness, safety, fitness, availability, regulatory compliance, or compatibility with any device, network, or version of macOS.

Low-level driver development can cause system instability, kernel or system extension failures, USB device malfunction, data loss, network disruption, unexpected radio transmission, or security exposure. Disabling SIP or reducing startup security materially weakens macOS protections.

To the maximum extent permitted by applicable law, the author and contributors are not responsible for damage to hardware or software, data loss, service interruption, privacy violations, regulatory violations, unauthorized access, interference, or other consequences arising from installation, testing, modification, distribution, or misuse of this project.

Use of this repository does not grant permission to access, monitor, test, or transmit on any system, device, network, or radio channel.

Firmware and third-party material

Firmware binaries are not stored in Git source history or source archives. Local application builds may bundle the three pinned MediaTek files together with their separate redistributable license.

Third-party notices, license boundaries, and pinned provenance information are recorded in:

• THIRD_PARTY_NOTICES.md
• Documentation/UPSTREAM_PROVENANCE.md
• Documentation/LEGAL_AND_PROVENANCE_AUDIT.md

License

The project core is licensed under the MIT License unless a file or integration states otherwise. Some integration or compatibility files have separate license requirements. Review LICENSE, file-level SPDX identifiers, and THIRD_PARTY_NOTICES.md before redistribution.

ALFA, MediaTek, Apple, macOS, Bluetooth, Wi-Fi, and other product names are the property of their respective owners. This independent project is not endorsed by or affiliated with those owners. Public binary distribution may require separate Apple entitlements, Bluetooth qualification, and trademark review.

Maintainer

AlfaMacDriver is designed and maintained by Mohallab Kanan.

Contributing

Contributions should:

• Preserve the versioned IOUserClient ABI and input-validation boundaries.
• Include tests for new protocol, parser, and lifecycle behavior.
• Avoid adding firmware, captures, signing assets, personal data, or generated build products.
• Document upstream provenance and license obligations.
• Keep raw injection explicitly authorized and policy-restricted.
• Avoid claims of hardware support that are not backed by reproducible tests.

Open an issue before submitting a large architectural change.