Native apps and shared code
Android uses Kotlin, Jetpack Compose and Material 3 with native Keystore, Bluetooth, companion-device, notification and document-provider APIs. The Mac app uses Swift 6, SwiftUI and AppKit with Security/Keychain, Core Bluetooth, Network.framework, pasteboard, audio, Shortcuts and system Bluetooth HID integration.
The shared runtime is a small Rust bridge for OPAQUE PIN pairing—not a shared UI or general networking engine. Versioned contracts, CDDL schemas and independent test vectors define the cross-platform messages. Identity storage, transport adapters, lifecycle policy and feature owners remain native.
- Native identityLocal keys and validated public credentials
- Pairing and trustAuthenticated bootstrap and approval on both devices
- EDHOC and readinessFresh authenticated sessions for each transport
- Secured DATABounded records routed to native feature owners
Mac → Android keyboard and trackpad input follows a separate system Bluetooth HID path. It does not use aniCe’s application record channel.
Native app overview ↗ · Rust pairing bridge ↗ · Protocol index ↗
Device identity and trust
Each device owns a P-256 signing key. Android uses AndroidKeyStore and reports its actual hardware/software protection. Current Mac builds select development Keychain storage; a separate signed backend can prefer Secure Enclave, but still requires verification. The current app does not claim hardware isolation on Mac.
Public identity v1 includes a UUID-v4 device ID, platform, display name, a 65-byte uncompressed P-256 public point and its SHA-256 fingerprint. Native signatures cross the identity boundary as strict ASN.1 DER. Names and protection labels are display metadata, not trust credentials.
Trust is pinned to the full peer credential and the current local identity. Resetting identity retires sessions and automatic setup; pairing must be repeated. Forgetting a device removes local trust, not the other device’s records. Renaming does not replace the key or device ID.
QR and PIN pairing
Mac is the pairing server/peripheral; Android scans and initiates. QR invitations carry an ephemeral rendezvous, a 256-bit pre-shared secret and a SHA-256 commitment to the Mac identity fingerprint. Fresh P-256 ECDH, transcript binding and HKDF-SHA256 derive the bootstrap keys.
Six-digit PIN pairing uses an in-memory OPAQUE PAKE bridge with opaque-ke 4.0.1, Ristretto255, TripleDH/SHA-512 and Argon2id. It is not a plaintext PIN exchange or a permanent password login. Inner identity, proof, approval, receipt and cancellation messages use directional AES-256-GCM.
Both screens require approval before activating local trust. Signed receipts confirm each device’s durable local journal; completion across two devices is not a distributed atomic transaction. An invitation lasts 120 seconds, authentication is bounded to 30 seconds, approval to 60 seconds within the invitation, and five failed authentication attempts invalidate it. Logical pairing messages are limited to 4,096 bytes.
Pairing encoding, cryptography and deadlines ↗ · Pairing steps
Authenticated sessions and encrypted records
Already-trusted devices perform RFC 9528 EDHOC: method 0, cipher suite 5, P-256, SHA-256 and ChaCha20-Poly1305, with mandatory message 4. Unsupported methods, suites, extra authorization data and malformed deterministic CBOR are rejected. A fresh handshake matches the selected pinned identity; discovery cannot replace that credential.
Application records use exporter-derived AES-256-GCM, not EDHOC’s ChaCha20-Poly1305. Each direction has its own key, IV base and strictly ordered 64-bit counter. The 14-byte header, session ID and direction are authenticated; the 12-byte nonce combines the IV base with the counter, and records carry a 16-byte GCM tag. A reserved send counter is burned even if sealing or submission fails; it is never rolled back or resealed.
Encrypted ready/readyAck completes before application DATA is admitted. Readiness has a ten-second deadline; sessions have a 120-second authenticated idle bound, a one-hour age limit and 2^20 records per direction. BLE/standard DATA plaintext is at most 4,000 bytes; negotiated LAN profile 4 allows 524,416 bytes, including the transfer envelope.
Both transports authenticate independently and never share keys, IVs or counters. Native identity and active trust are rechecked on authenticated operations. Radio identifiers, timing and lengths remain observable; encrypted sessions are not a claim of anonymity.
Bluetooth discovery and GATT framing
BLE discovery is an unauthenticated compatibility probe. Mac advertises the service UUID and generic aniCe name, not device names, public identities or fingerprints. Its read-only discovery value is exactly 20 bytes: version, optional flags and a 16-byte nonce. Successful discovery does not establish trust or enable features.
The stable GATT service has discovery, write-with-response and indication characteristics. Android is the central and Mac the peripheral; aniCe does not request BLE bonding. Pairing uses fragmentation v1 and trusted sessions use fragmentation v2. Session fragments are contiguous, logical messages are capped at 4,096 bytes, and reassembly expires after ten seconds.
The BLE session queue is bounded to eight logical messages/32 KiB. Android caps native characteristic values at min(MTU − 3, 512) bytes: MTU 517 still uses at most 512-byte values, including the fragmentation header. A candidate or retained subscription must authenticate afresh; it cannot resume old record keys.
Independent local-network transport
Manual LAN can connect already-paired devices without Bluetooth. Android uses Wi-Fi; Mac can use Wi-Fi or Ethernet. Bonjour/Android NSD discovers anonymous _anice._tcp instances. A locator or TXT record grants no trust: the selected device ID, fingerprint and public key must pass fresh EDHOC authentication.
LAN carries bounded session envelopes over TCP, with a five-byte version/length frame header. Current apps advertise TXT revision 3 and negotiate record/frame profile 4 before EDHOC; this is distinct from File Transfer protocol v1 and its capability versions. Current Mac listeners require revision 3/profile 4, so update both apps.
Profile 4 bounds an envelope to 524,447 bytes and its transport queue to four envelopes/2,097,788 envelope bytes. Handshakes remain limited to 4,096 bytes. Before readiness, partial headers/handshakes have ten seconds total; established encrypted-record assembly permits ten seconds without byte progress, capped at sixty seconds total. Socket writes retain a ten-second deadline.
BLE and LAN can coexist only for the same pinned peer under a shared reservation. Automatic LAN is a separate preference on both devices: authenticated BLE events and eligible feature demand coordinate bounded admission, without broadcasting identities or exchanging LAN endpoints over BLE. Manual LAN discovery/authentication stays independent. Network loss, firewall or multicast isolation can prevent a connection; sharing a router does not guarantee reachability.
LAN wire contract ↗ · Automatic rendezvous ↗ · Native LAN ownership ↗
Lifecycle, liveness and renewal
Application-scoped owners respond to platform events and the earliest absolute monotonic deadline, rather than a one-second polling loop. Quiet deadline evaluation performs no Keystore, Keychain or trust-journal reads; authenticated operations still perform live validation. Old operation generations cannot retire or deliver DATA into replacement sessions.
Android API 31+ uses an OS-bound CompanionDeviceService for opt-in background BLE ownership. API 29–30 retain manual foreground connections. A companion association is an OS lease/locator, not authentication. Foreground activities, bounded pickers, approved transfer-service work and eligible companion media demand have distinct ownership. Android’s LAN idle timeout defaults to Never, but network loss, process loss and session limits still apply.
Mac windows and the menu-bar companion share connection owners. Closing the window does not quit the app; sleep retires channels, wake reevaluates enabled policy, and Quit stops work. Explicit Disconnect pauses automatic work before teardown. Timed pauses close current channels and store one resume deadline; they do not retain an active transfer connection.
Encrypted HELLO/ACK negotiates liveness. Android sends PING after sixty seconds without authenticated activity; a correlated PONG is due within twenty seconds. Automatic BLE renewal starts at 55 minutes or 2^20 − 1024 records, retires the old channel, then performs fresh EDHOC/readiness. Manual LAN needs another Connect after expiry; automatic LAN waits for an eligible event or demand rather than an independent retry timer.
Background APIs, leases and retries ↗ · Control message schema ↗
DATA delivery, ownership and backpressure
Native feature owners register with FeatureDispatch. Each authenticated channel descriptor carries its instance, transport and pinned peer binding. Readiness, capacity, retirement and generation checks gate every callback. SecuredChannel rejects retired instances and records beyond the negotiated profile.
Android framing, cryptography and socket work stay off the presentation dispatcher; UI mutation returns to its native owner. Mac uses transport/storage actors and separate decode workers. Shared dispatch admits transfer chunks into a feature-owned bounded FIFO instead of awaiting their file writes. A full FIFO suspends ingress; it does not drop accepted chunks or issue progress/ACKs before storage succeeds.
Session admission retains at most eight waiting callers before sealing, prioritizes standard-sized requests, and grants a bulk turn after four small turns when both classes wait. Cancellation removes unadmitted work before nonce reservation. Once a nonce is reserved, the session owns completion or retirement independently of the producer. Already-submitted TCP bytes remain ordered and cannot be overtaken by a later control.
Transfer ingress is capped at 2 MiB including active work, with at most 64 records within negotiated limits. Resume verification shares the ordered worker with chunk writes. Retirement and cancellation fence pending and active completions; normal EOF/authenticated close allows accepted work at most ten seconds to drain.
Application DATA ownership ↗ · Admission, allocation and hot-path details ↗
File transfer, storage and recovery
File Transfer v1 streams one sequential batch of 1–128 regular local files to a trusted, compatible peer. Offers capture the selected recipient, destination and that sender’s receive consent. New pairings enable automatic receiving; existing peers retain their saved choice. Otherwise, the receiver must approve the offer.
| Channel / capability | Maximum chunk | Maximum outstanding file data |
|---|---|---|
| BLE / 1 | 3,072 bytes | 4 chunks / 12 KiB |
| Legacy LAN / 2 | 131,072 bytes / 128 KiB | 8 chunks / 1 MiB |
| Legacy LAN profile 3 / 3 | 262,016 bytes | 8 chunks / 2,096,128 bytes |
| LAN profile 4 / 4 | 524,288 bytes / 512 KiB | 8 chunks / 4 MiB |
BLE’s contract ceiling is 64 chunks; the current native receivers advertise four. Large-chunk LAN senders start each file/resume with an acknowledged probe of at most 4,096 bytes. A confirmation within 100 ms qualifies the negotiated window. Delayed acknowledgement paths shrink to at most two 65,536-byte chunks/128 KiB, within peer credit; a fresh probe can restore the window after its cooldown. ACKs follow successful local writes, not queue admission; final length and SHA-256 verification precede publication.
The transfer implementation separates coordinator, sender, receiver, recovery and storage roles. Sources are streamed; incoming job-owned partials are checked with incremental SHA-256 before non-overwriting publication. Mac uses exclusive same-filesystem publication. Android defaults to pending MediaStore entries and uses validated document-tree grants for custom destinations; provider rename/copy publication is not guaranteed atomic. Verification is not malware scanning.
Connection loss retains verified prefixes and private recovery journals for fifteen minutes. A fresh authenticated LAN connection to the same trusted peer resumes after prefix verification; after LAN loss, Bluetooth continuation requires an explicit action. Prepared jobs can recover across app restarts, but unfinished initial hashing/file selection cannot. Cancel removes unfinished partials, not already-published files. Folders, symbolic links and unavailable cloud-only files are unsupported.
Transfer contract ↗ · Native routes, receiving and recovery ↗ · Website setup guide
Feature protocols and native boundaries
Pairing does not grant every permission or enable every feature. Owners use negotiated capabilities, per-feature consent and platform permissions. The protocols below use existing authenticated DATA unless noted.
- Clipboard v1 and link handoff
- Plain text/links up to 64 KiB, bounded fragmentation and in-memory cross-transport deduplication. Automatic sharing is off by default and Android reads require actual input focus. Text-selection/Share actions pass supplied text directly; the Quick Settings tile opens a focused manual-read panel. Open in Mac hands an HTTP(S) URL to the Mac browser without replacing its clipboard. Clipboard behavior ↗ · Contract ↗
- SMS relay v3
- Android is the provider/source of truth. Bounded thread, history and search pages, multipart reassembly and active-SIM selection run through native SMS owners. Mac conversation data is in memory and cleared when the final peer link retires. RCS and MMS sending are unsupported; there is no persistent Mac search index. SMS behavior ↗ · Contract ↗
- Notification mirroring v1
- Selected Android app alerts, revision-bound replies/actions and synchronized dismissal are reconciled across channel changes. Source icons use LAN. aniCe and the default SMS app are excluded; Mac retains no notification history or offline queue. SIM call controls and caller identity need separate phone permissions; audio remains on the phone. Notification behavior ↗ · Contract ↗
- Now Playing v1 and volume capabilities
- One application-scoped MacPlaybackModel owns state, selection and observation leases. A native adapter bridge is fenced by launch generation; session subscriptions and commands bind to the current revision. Supported output and selected-player volume are negotiated independently. Artwork uses LAN; audio keeps playing on Mac. Background Android controls require existing eligible ownership. Playback behavior ↗ · Media contract ↗
- Desk Deck v1–v5 and Device Power v1
- Foreground, lease-bound Mac telemetry and controls include CPU, memory, OS thermal pressure, power, approved app shortcuts, a configured DND Shortcut and revisioned audio-output selection. Controls bind to the subscription and hardware target. Screenshot opens Mac’s native controls; it does not transmit an image. Temperature and display brightness are not advertised. Device Power reports battery/charging on already-open channels without acquiring a new connection lease. Desk Deck behavior ↗ · Desk Deck contract ↗ · Device Power ↗
- Phone → Mac input v1
- Authenticated BLE carries committed Unicode text separately from key transitions, with coalesced pointer/scroll motion and fail-safe release. Mac Event Posting permission is required. Leaving Control Mac stops input without directly disconnecting BLE; this is not screen mirroring. Input behavior ↗ · Contract ↗
- Mac → Android system HID
- A native Classic Bluetooth HID service sends keyboard/pointer reports to a system-paired Android host. The user confirms a link between the full aniCe credential and that OS Bluetooth device. macOS manages current Bluetooth authentication/encryption, without independent aniCe verification. This is separate from EDHOC/AES-GCM and adds no aniCe network message or Android service. Control Android and Floating Key ↗ · HID contract ↗
- Do Not Disturb sync v1
- Android interruption-filter changes call locally selected On/Off Shortcuts on Mac over an existing channel. This owner is independent of Desk Deck; it does not poll, replay offline changes or support Mac → phone sync. DND behavior ↗ · Contract ↗
- Find Device v1
- Correlated alert requests use an existing trusted connection and report OS submission results. They do not provide location tracking, establish a connection, or guarantee that a notification/sound is presented despite OS restrictions. Find Device behavior ↗ · Contract ↗
Storage and privacy
Identity keys and trust are local to each device. Handshake/session keys and counters stay in memory and are not persisted or logged. Native buffer overwrite/object release is best effort on JVM and Swift, not a guaranteed erasure claim. A compromised host OS is outside the documented protection boundary.
Clipboard history is a separate, default-off local owner with 20/50/100-item capacity. Pausing collection, restarting, resetting identity or forgetting trust preserves saved history; users must delete it explicitly. Recent clipboard activity is process-local and retained for five minutes, independently of history. Mac SMS content is memory-only; notifications and artwork have no history cache.
File contents are saved to the selected local destination after verification. Peer data travels directly over Bluetooth/LAN, not a cloud relay. Update metadata and downloads use GitHub HTTPS; user-submitted bug reports also use GitHub. About → Report an issue supplies app/OS versions for user review, without automatically attaching messages, files, identities or logs. aniCe has no analytics service.
Security scope and privacy boundaries ↗ · Clipboard history guide
Release signing and update security
Official artifacts are aniCe-android.apk and the Apple-silicon aniCe-mac.zip. Release tags, platform versions and build numbers share an ordering. Stable releases are selected by default, even on beta installs; including betas requires opt-in confirmation.
Discovery is separate from peer networking: bounded HTTPS metadata/downloads, conditional requests, retry spacing and an Atom fallback for rate limiting. Downloads are restricted to expected GitHub hosts/asset paths. Metadata alone never authorizes installation.
- Android: verify package, version and signing lineage, then hand the APK to the system installer for confirmation. A differently signed development APK is not updated in place by a production artifact.
- Mac: validate archive paths, bundle identity/version, arm64 code and pinned leaf certificates. A separately signed helper uses a nonce-bound record and atomic bundle exchange; the previous bundle is retained until the new main window confirms startup. Failed startup attempts rollback/relaunch, not guaranteed recovery under every filesystem failure.
Current Mac artifacts are self-signed and not Apple-notarized. Signing rotation requires planning for users who skip releases. The release workflow gates builds/publication on successful CI, signing configuration, a verified-device source commit and uploaded artifact digests; it does not make a development version a published release.
Installation, signing and update recovery ↗ · Published releases ↗
Performance targets and measured workload
Record overhead, native key/trust validation, payload copies, scheduling and destination storage all affect throughput. At the 8 MiB/s LAN acceptance gate, 4,000-byte records would require about 2,097 records per second, versus sixteen full 512-KiB chunks. Larger negotiated records amortize per-record work; they do not remove validation or guarantee Wi-Fi and storage performance.
| Metric | Documented target | Evidence required |
|---|---|---|
| LAN file throughput | At least 8 MiB/s each way | Physical-device benchmark |
| Control round trip | At most 100 ms with 25 ms added latency | Physical-device benchmark |
| Connected-idle CPU | At most 0.5% of one core | Objective; matched idle sampling |
The native background guide reports matched Debug/USB connected-idle BLE tests: two minutes of warm-up, then three five-minute samples. Median single-core CPU fell from 3.166% to 0.322% on Android and 0.385% to 0.030% on Mac after event-driven maintenance replaced periodic polling. Connection continuity, manual-check counts and identity/trust journal bytes stayed unchanged. These results show relative workload reduction on the test hardware, not unplugged battery consumption or universal device performance.
Active playback is a different workload. The performance guide records interactive Debug observations of roughly 15–20% Mac app CPU with optional Home/companion Now Playing, peaking around 35% during concurrent phone-to-Mac transfer. Those are not controlled Release profiles. Release, battery, minimum-OS, deep Doze and broader responsiveness acceptance remain separate work.
Opt-in native timing separates admission, validation, seal/open, transport, ingress and storage using local monotonic timestamps. Local submission is not peer receipt; nested timings must not be added together, and peer clocks are not synchronized. Raw TCP diagnostics exclude encrypted records, transfer credit and file storage, so their rates cannot stand in for production transfers.
Cost model, timing and measurement tiers ↗ · Idle sampling procedure and results ↗ · Physical LAN acceptance contract ↗
Verification and current limits
Host tests, independent crypto/CBOR fixtures and native interchange checks cover encodings, handshake agreement, record bounds, cancellation and generation fencing. Physical packaged-app checks provide a separate tier for actual radio/network/storage behavior. None of these is an independent cryptographic audit.
The documented performance targets are acceptance gates, not promised rates. Host checks establish wire behavior and arithmetic, not physical radio throughput, Keystore latency or battery endurance.
- Minimum-version physical acceptance for Android API 29 and macOS 14 remains pending; supported targets are not a claim that every device combination is verified.
- General BLE foreground-service fallback, Android reboot recovery, automatic Mac login launch, manual LAN IP entry and coordinated LAN renewal are not implemented.
- Permission denial, sleep, force-stop, Wi-Fi changes and native service loss can interrupt availability. Automatic background access is not unrestricted.
- The current Mac app is unsandboxed and uses development Keychain storage. Secure Enclave isolation, Apple notarization and an independent security review must not be inferred.
- The browser simulator is illustrative only. It does not test cryptography, connect devices or establish native capability support.
Native documentation and follow-up reading
Based on the aniCe app repository’s architecture and related native documents on main, reviewed at b395ed3. Protocol contracts define the wire behavior; unfinished work is identified in the current limits.
These references belong to the aniCe application repository, not the website or browser simulator. The native root architecture, feature guides and protocol contracts are the sources for this page.