From acbcf2f9926406fdebb3ebe2dea00cdb8c6caa06 Mon Sep 17 00:00:00 2001 From: James Magahern Date: Sat, 6 Sep 2025 19:52:37 -0700 Subject: [PATCH] AI generated READMEs --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++ android/README.md | 47 ++++++++++++++++++++++++++++ core/README.md | 68 ++++++++++++++++++++++++++++++++++++++++ mock/README.md | 40 ++++++++++++++++++++++++ osx/README.md | 31 ++++++++++++++++++ 5 files changed, 266 insertions(+) create mode 100644 README.md create mode 100644 android/README.md create mode 100644 core/README.md create mode 100644 mock/README.md create mode 100644 osx/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ec98272 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# Kordophone Monorepo + +Kordophone is an iMessage bridge: a lightweight server runs on a Mac and exposes an HTTP API so non‑Apple devices can send/receive iMessages. A set of clients (Android, Linux GTK, macOS Cocoa) talk to that API. A shared Rust library powers most clients, and a mock server helps local testing. + +> Important: Interfacing with iMessage on macOS involves private APIs and restricted entitlements. See `server/README.md` for details and safety notes. + +## Repository Layout + +Top‑level projects in this monorepo: + +- `server/` — macOS daemon that bridges to iMessage and exposes an HTTP REST API. Written in Objective‑C/Cocoa. See `server/README.md`. +- `core/` — Rust workspace with the shared Kordophone client library and related tooling. Used by `gtk/` and `osx/`. +- `gtk/` — GTK4/Libadwaita Linux desktop client built on the Rust `core` library. +- `osx/` — macOS Cocoa client that uses the Rust `core` library and talks to the local Kordophone client daemon via XPC. +- `android/` — Android client. Currently implements its own API client (does not use the Rust library yet). +- `mock/` — Go‑based mock server that emulates a Mac running the Kordophone server, for local development and tests. + +Quick links: + +- Server (mac daemon): `server/` +- Core (Rust workspace): `core/` +- GTK client (Linux): `gtk/` +- macOS client (Cocoa): `osx/` +- Android client: `android/` +- Mock server (Go): `mock/` + +## How It Works + +1. The macOS Kordophone Server (`server/`) runs on a Mac with iMessage and exposes an HTTP/JSON API and a WebSocket/updates channel. +2. Clients connect to that server to list conversations, fetch/send messages, upload/download attachments, and receive live updates. +3. A Rust library in `core/kordophone` implements the wire protocol and client behaviors. Linux/macOS clients use this library directly; Android currently ships a native Kotlin client. +4. The Rust client daemon (`core/kordophoned`) provides local caching and IPC (D‑Bus on Linux, XPC on macOS) for GUI apps. +5. The `mock/` server simulates the server API for local development without a Mac. + +## Getting Started + +You can try the clients quickly against the mock server. + +1) Run the mock server (no auth): + +```bash +cd mock +go run ./... # or: make; ./kordophone-mock +``` + +The mock server listens on `http://localhost:5738` and serves endpoints like `/conversations`, `/messages`, `/sendMessage`, `/attachment`, `/updates`. + +2) Point a client at the mock server: + +- Android: open Settings in the app and set the server host to `http://10.0.2.2:5738` (Android emulator) or `http://:5738` if running on device. Disable auth unless you started the mock with `--auth`. +- GTK (Linux): build and run the GTK app from `gtk/` (see its README) and configure it to use the local daemon backed by the server URL. +- macOS (Cocoa): build the app in `osx/` (see `osx/README.md`). + +To use a real Mac server instead, set your client’s server URL to the host running `server/` with the correct scheme/port and authentication. + +## Building + +Below are brief notes. Each subproject’s README has more detail. + +- Server (macOS): open `server/MessagesBridge.xcodeproj` in Xcode. See `server/README.md` for entitlements, SSL, and running. +- Core (Rust): install Rust (stable) and run `cargo build` inside `core/`. See `core/README.md`. +- GTK (Linux): see `gtk/README.md` for RPM build via `rpmbuild -ba dist/rpm/kordophone.spec`. +- macOS (Cocoa): open `osx/kordophone2.xcodeproj` in Xcode. See `osx/README.md`. +- Android: open `android/` in Android Studio and build. See `android/README.md` for configuration. +- Mock server (Go): `cd mock && go run ./...` or `make`. + +## Security and Entitlements + +The macOS server uses private APIs and restricted entitlements. On production macOS builds, processes with restricted entitlements can be killed by the kernel; development requires workarounds (e.g., swizzling, hooking `imagent`) and careful code signing. See `server/README.md` for instructions and caveats. + +## Status + +- Android client: ships its own API client (not yet using Rust `core`). +- GTK + macOS clients: use the Rust `core` library and integrate with the `kordophoned` client daemon for caching/IPC. +- Mock server: useful for development; implements common endpoints and WebSocket updates. + +## Contributing + +Issues and PRs are welcome. If you add a new client or endpoint, please update relevant READMEs and link it from this root README. Prefer small, focused changes and keep style consistent with the existing code. + diff --git a/android/README.md b/android/README.md new file mode 100644 index 0000000..992115f --- /dev/null +++ b/android/README.md @@ -0,0 +1,47 @@ +# Kordophone Android Client + +Android client for the Kordophone iMessage bridge. This app connects to a running Kordophone server over HTTP/JSON and streams updates. + +Note: This client currently implements its own API layer in Kotlin and does not yet use the shared Rust `core` library. + +## Build & Run + +Requirements: + +- Android Studio (AGP 8.x) +- JDK 8+ toolchain (project uses Java 8 bytecode) + +Steps: + +1. Open `android/` in Android Studio. +2. Sync Gradle and build the project. +3. Run the `app` configuration on an emulator or device. + +The app targets `minSdk 30`, `targetSdk 33` and uses Jetpack Compose. + +## Configure Server + +Set the server host and optional Basic Auth from the app’s Settings screen. + +- Server URL for local mock (emulator): `http://10.0.2.2:5738` +- Server URL for local mock (device): `http://:5738` +- Credentials: match the server if auth is enabled (mock supports `--auth`). + +Settings are persisted using `EncryptedSharedPreferences`. + +## Modules + +- `app/` — UI (Compose), DI (Hilt), app wiring +- `backend/` — Kotlin API client, DB/cache (Realm), models, tests + +## Testing with the Mock Server + +Start the mock server in the repo root: + +```bash +cd mock +go run ./... # or: make; ./kordophone-mock +``` + +Set the app’s server URL to the mock address and run. The mock exposes `/conversations`, `/messages`, `/sendMessage`, `/attachment`, `/updates` and more. + diff --git a/core/README.md b/core/README.md new file mode 100644 index 0000000..9c6198c --- /dev/null +++ b/core/README.md @@ -0,0 +1,68 @@ +# Kordophone Core (Rust Workspace) + +This directory contains the shared Rust code and tools used by Kordophone clients. + +Workspace members: + +- `kordophone/` — Rust client library for the Kordophone HTTP/WebSocket API. Cross‑platform. +- `kordophone-db/` — Lightweight cache/database and models built with Diesel (SQLite). +- `kordophoned/` — Client daemon providing local caching and IPC + - Linux: D‑Bus + - macOS: XPC (see notes below) +- `kpcli/` — Command‑line interface for interacting with the API, DB, and daemon. +- `utilities/` — Small helper tools (e.g., testing utilities). + +## Build + +```bash +cd core +cargo build # build all workspace members +cargo test -p kordophone +``` + +Build a specific crate: + +```bash +cargo build -p kordophone +cargo build -p kordophoned --release +``` + +## `kordophoned` (Client Daemon) + +The daemon maintains a local cache, handles update cycles, and exposes IPC for GUI apps. + +- Linux: exposes a D‑Bus service (see service file in `kordophoned/include`). +- macOS: exposes an XPC service named `net.buzzert.kordophonecd`. + +macOS XPC registration (manual during development): + +```bash +cd core/kordophoned +launchctl load include/net.buzzert.kordophonecd.plist +``` + +The macOS GUI app (`osx/`) can programmatically register this during launch; see `osx/README.md`. + +### Packaging (RPM example) + +`kordophoned` is configured for RPM packaging via `cargo-generate-rpm`. + +```bash +cargo build --release +strip -s target/release/kordophoned +cargo generate-rpm +``` + +## `kpcli` (CLI) + +Useful for quick testing and interacting with the daemon/cache. + +```bash +cargo run -p kpcli -- --help +``` + +## Notes + +- TLS/WebSocket: the `kordophone` crate includes `rustls` and installs a crypto provider at process start. +- DB: `kordophone-db` includes Diesel migrations under `kordophone-db/migrations/`. + diff --git a/mock/README.md b/mock/README.md new file mode 100644 index 0000000..f7820cc --- /dev/null +++ b/mock/README.md @@ -0,0 +1,40 @@ +# Kordophone Mock Server (Go) + +A lightweight mock of the Kordophone macOS server for local development and tests. It emulates the REST API and updates stream, and seeds itself with sample conversations/messages/attachments. + +## Build & Run + +Requirements: Go 1.20+ + +```bash +cd mock +go run ./... # quick run + +# or build a binary +make # outputs ./kordophone-mock +./kordophone-mock +``` + +Flags: + +- `--debug` — enable debug logging +- `--auth` — require authentication (Bearer token via `/authenticate`) + +Listens on `http://localhost:5738` by default. + +## API Surface (mocked) + +- `GET /version` — server version +- `GET /status` — status (requires auth when enabled) +- `GET /conversations` — list conversations +- `GET /messages?guid=...&beforeDate=...&beforeMessageGUID=...&afterMessageGUID=...&limit=...` — list messages +- `POST /authenticate` — exchange username/password for a bearer token (when `--auth`) +- `POST /sendMessage` — send a message +- `POST /markConversation?guid=...` — mark read +- `GET /attachment?guid=...` — download attachment +- `POST /uploadAttachment?filename=...` — upload attachment +- `GET /pollUpdates?seq=...` — long‑poll for updates +- `GET /updates` — WebSocket updates + +Note: `/api/*` paths are redirected to the same endpoints for compatibility. + diff --git a/osx/README.md b/osx/README.md new file mode 100644 index 0000000..ce2b68f --- /dev/null +++ b/osx/README.md @@ -0,0 +1,31 @@ +# Kordophone macOS Client (Cocoa) + +SwiftUI/Cocoa client for Kordophone on macOS. This app uses the Rust `core` library via the local client daemon (`kordophoned`) and communicates over XPC. + +## Project + +- Open `osx/kordophone2.xcodeproj` in Xcode. +- Target bundle id: `net.buzzert.kordophone2`. + +## XPC + Daemon + +The macOS client talks to the `kordophoned` XPC service (`net.buzzert.kordophonecd`). During development, register the daemon with launchd: + +```bash +cd core/kordophoned +launchctl load include/net.buzzert.kordophonecd.plist +``` + +The app can also register programmatically using `SMAppService` (see inline comments in `XPC/XPCClient.swift`). + +## Running + +1. Ensure the XPC service is registered and the `kordophoned` binary is available (see `core/README.md`). +2. Build and run the `kordophone2` app. +3. Configure the app to point the daemon at your Kordophone server URL (mock or real). + +## Notes + +- Attachments are staged under the user’s temp directory (see `Attachments.swift`). +- Entitlements and daemon files are included under `kordophone2/Daemon/` and `Supporting Files/`. +