AwesomeREA.org

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.

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. This record names no accounts, identifiers or credentials, and the certificate file in the test assets is deliberately not linked.
  • 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. This source review ran no tests, activation or connections.
  • 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. The reviewed sources establish no AI or REA use.

About this entry

Type
Case study
Category
Independent reconstruction cases
Relationship
Independent reconstruction project
Targets
Protocol

Sources reviewed

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Report an outdated entry Suggest a translation fix

Primary sources

  1. README.md GitHub · JJTech0130/pypush · Revision 71aa2e4
  2. pyproject.toml GitHub · JJTech0130/pypush · Revision 71aa2e4
  3. LICENSE GitHub · JJTech0130/pypush · Revision 71aa2e4
  4. pypush GitHub · JJTech0130/pypush · Revision 71aa2e4
  5. pypush/apns/__init__.py GitHub · JJTech0130/pypush · Revision 71aa2e4
  6. pypush/apns/lifecycle.py GitHub · JJTech0130/pypush · Revision 71aa2e4
  7. pypush/apns/protocol.py GitHub · JJTech0130/pypush · Revision 71aa2e4
  8. pypush/cli/__init__.py GitHub · JJTech0130/pypush · Revision 71aa2e4
  9. tests/test_apns.py GitHub · JJTech0130/pypush · Revision 71aa2e4
  10. .github/workflows/lint.yml GitHub · JJTech0130/pypush · Revision 71aa2e4
  11. https://github.com/JJTech0130/pypush/releases/tag/v2.0.2
  12. https://pypi.org/project/pypush/2.0.2/

More in Protocols

All 27 entries in ProtocolsProtocols case studies (9)