Case study
pypush: a Python client for Apple’s push protocol
Reimplements the client side of Apple’s private Apple Push Notification service (APNs) protocol in platform-independent Python: it activates as an Apple device, connects to the APNs courier, mints app-scoped tokens and receives push notifications. The project began as the author’s proof of concept for iMessage reverse engineering, but the current rewrite has removed IDS and iMessage support for now. It uses Apple’s services outside Apple’s official clients.
- Targets
- Protocol
- Category
- Independent reconstruction cases
- Relationship
- Independent reconstruction project
- Sources reviewed
Requirements & limits
- Reviewed at the 2026-03-15 main head, identical to release v2.0.2 on PyPI. The README warns that the rewrite is unstable, that many features have been temporarily removed and that stability should not be expected before 3.0.0. The IDS, iMessage, GrandSlam and CloudKit packages are empty placeholders, so the earlier iMessage work is not part of this version.
- Activation and connections go to Apple’s live activation and APNs servers through what the project calls Apple’s internal API, outside Apple’s official clients; the README notes that some APIs may need device identifiers. Apple’s terms for these services apply separately.
- Requires Python 3.9+ with anyio, httpx (HTTP/2) and cryptography; the cli extra adds Frida, Rich and Typer. The CLI listens for notifications on a topic, and its proxy mode, meant for observing a Mac’s own APNs traffic, attaches Frida to the local apsd daemon and requires System Integrity Protection disabled and root.
- Pull-request CI runs Ruff and pytest on Python 3.9–3.12 across Linux, macOS and Windows. The tests activate against Apple’s servers, open an APNs connection and round-trip a sandbox notification through a scoped token, so they depend on live services rather than offline protocol fixtures.
- LICENSE is the Server Side Public License v1, and the package metadata classifies it as Other/Proprietary; the README says Beeper purchased the project and directs licensing questions to Beeper.
About this entry
The description was reviewed against primary sources.
Primary sources
- README.md GitHub · JJTech0130/pypush · Revision 71aa2e4
- pyproject.toml GitHub · JJTech0130/pypush · Revision 71aa2e4
- LICENSE GitHub · JJTech0130/pypush · Revision 71aa2e4
- pypush GitHub · JJTech0130/pypush · Revision 71aa2e4
- pypush/apns/__init__.py GitHub · JJTech0130/pypush · Revision 71aa2e4
- pypush/apns/lifecycle.py GitHub · JJTech0130/pypush · Revision 71aa2e4
- pypush/apns/protocol.py GitHub · JJTech0130/pypush · Revision 71aa2e4
- pypush/cli/__init__.py GitHub · JJTech0130/pypush · Revision 71aa2e4
- tests/test_apns.py GitHub · JJTech0130/pypush · Revision 71aa2e4
- .github/workflows/lint.yml GitHub · JJTech0130/pypush · Revision 71aa2e4
- https://github.com/JJTech0130/pypush/releases/tag/v2.0.2
- https://pypi.org/project/pypush/2.0.2/
More in Protocols
- PixMob IR reverse engineering: controlling event wristbands at home · Case study
- OpenDrop: an open reimplementation of Apple AirDrop · Case study
- bluefluff: reverse engineering Furby Connect's Bluetooth LE protocol · Case study
- pyatv: a reverse-engineered client for Apple TV and AirPlay protocols · Case study
- BudsPro-Headtracking: streaming Galaxy Buds Pro head tracking over Samsung’s serial protocol · Case study
- Even G2 protocol: reverse-engineering Even Realities G2 smart-glasses BLE traffic · Case study