diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e5fd6c..76767ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -87,6 +87,14 @@ scripts/repo-maintenance/validate-all.sh For documentation-only work, also inspect the changed Markdown structure and links. Do not run visible apps, simulators, GUI automation, or disruptive service checks without approval. +Automated validation and runtime evidence prove different things: + +- Swift tests should cover deterministic parsing, target metadata, formatting, and reusable helper behavior. +- Builds prove that the checked-in source compiles against the selected toolchain. +- Runtime captures prove the observed private-framework, daemon, notification, Accessibility, permission, or entitlement behavior only for the recorded environment. + +Do not convert an environment-specific observation into a unit-test claim, and do not describe a passing build or test as proof that a private runtime surface is present, permitted, or stable across OS versions. + ## Pull Request Expectations Summarize the target, evidence gathered, conclusions promoted, commands run, environment used, and any remaining inference or blocked runtime proof. Keep reviewable raw captures separate from generated or ignored bulk output. diff --git a/README.md b/README.md index 7f32584..54db746 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,28 @@ Individual probes may require a particular macOS build, private frameworks, TCC ## Usage -The safest starting points are the read-only commands: +Start with the target inventory, then read the target overview linked from [`docs/README.md`](./docs/README.md): + +```sh +swift run spelunk targets +``` + +### Command Safety + +These commands are read-only in intent: they do not send playback commands, change routes, dismiss notifications, or alter account or message state. Loading private frameworks and querying system services can still fail because of OS, entitlement, TCC, sandbox, or SIP boundaries. + +| Command | Purpose | Runtime Boundary | Output | +| --- | --- | --- | --- | +| `swift run spelunk targets` | List every seeded research target and its documentation paths. | None beyond building the package. | Human-readable target index. | +| `swift run spelunk notifications --max-depth 6` | Inspect the Notification Center Accessibility tree. | Requires Accessibility trust to expose the tree; captured strings may contain personal notification content. | JSON capability and tree snapshot. | +| `swift run spelunk objc-runtime ...` | Load selected framework images and inventory matching Objective-C metadata. | The requested image is loaded into the probe process; private images may reject loading or execute framework initialization. | Text or JSON metadata. | +| `swift run spelunk string-constants ...` | Resolve selected exported string constants from a framework image. | Loads the requested image; symbols may be absent or use an unsupported representation. | Text or JSON resolution results. | +| `swift run spelunk notification-observe ...` | Observe named Darwin or distributed notifications for a bounded duration. | Waits for live events; payload contents are not recorded. | Text or JSON registration and event results. | +| `swift run mr-now-playing-probe [options]` | Query MediaRemote now-playing, client, player, origin, or queue state. | Contacts private media services; some options register notifications or issue read requests. | Human-readable runtime observations. | +| `swift run mr-interface-probe` | Inspect selected MediaRemote Objective-C runtime interfaces. | Loads the private framework into the probe process. | Human-readable class and method inventory. | +| `swift run mr-route-probe [options]` | Query endpoints, routes, contexts, and output-device metadata. | Contacts private routing services; default invocation does not change the active route. | Human-readable route observations. | + +Common read-only examples: ```sh swift run spelunk notifications --max-depth 6 @@ -50,7 +71,7 @@ swift run mr-interface-probe swift run mr-route-probe ``` -The package also contains `mr-internal-probe`, `now-playing-fixture`, and the `MRXPCTraceInterpose` dynamic library for narrower experiments. Repeatable MediaRemote capture helpers live under [`tools/`](./tools/README.md). +The package also contains `mr-internal-probe`, `now-playing-fixture`, and the `MRXPCTraceInterpose` dynamic library for narrower experiments. These are not general starting points: read the [MediaRemote experiment documentation](./docs/frameworks/MediaRemote/experiments.md) before using them. Repeatable MediaRemote capture helpers and their individual purposes live under [`tools/`](./tools/README.md). For each target, use: @@ -64,6 +85,8 @@ Every writeup should identify the active OS and SDK or Xcode version, distinguis For research intake, local setup, validation, documentation boundaries, and review expectations, see [`CONTRIBUTING.md`](./CONTRIBUTING.md). Durable agent-facing rules live in [`AGENTS.md`](./AGENTS.md), and planned work lives in [`ROADMAP.md`](./ROADMAP.md). +Automated tests cover deterministic, reusable helper behavior. Environment-specific private-framework calls, daemon responses, permissions, and OS behavior require a documented runtime observation; a passing unit test or build does not prove that those live surfaces are available or authorized on another machine. + ## Repo Structure ```text diff --git a/ROADMAP.md b/ROADMAP.md index cbc2811..1d1f201 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -29,10 +29,15 @@ Build a trustworthy public knowledge base and set of local tools for understandi ## Milestone Progress -- Milestone 0: Repository Foundation - Completed -- Milestone 1: MediaRemote Baseline - In Progress -- Milestone 2: Media Control Experiments - Planned -- Milestone 3: Reusable Research Tooling - In Progress +| Workstream | Status | Current Boundary | +| --- | --- | --- | +| Repository foundation | Completed | SwiftPM, documentation, evidence, validation, and maintenance structure established. | +| MediaRemote | In Progress | Read-only baseline and runtime probes established; interface recovery and non-empty now-playing reproduction remain open. | +| Messages | Baseline Established | Supported/private boundary, storage, runtime, notification, and XPC ownership maps captured; deeper interface and event proof remains open. | +| Phone | Baseline Established | Supported/private boundary, storage, runtime, notification, and XPC ownership maps captured; deeper interface and event proof remains open. | +| UserNotifications | Baseline Established | Read-only Notification Center Accessibility and runtime inventory established; broader state and OS comparisons remain open. | +| Media control experiments | Planned | Mutating command and route experiments remain gated on explicit, bounded research slices. | +| Reusable research tooling | In Progress | Target index, notification, Objective-C runtime, string-constant, and MediaRemote capture helpers exist; generalized capture and reporting remain open. | ## Milestone 0: Repository Foundation diff --git a/Sources/SpelunkingKit/SPKResearchTarget.swift b/Sources/SpelunkingKit/SPKResearchTarget.swift index 9910ee8..fc08367 100644 --- a/Sources/SpelunkingKit/SPKResearchTarget.swift +++ b/Sources/SpelunkingKit/SPKResearchTarget.swift @@ -38,4 +38,11 @@ public extension SPKResearchTarget { documentationPath: "docs/frameworks/MediaRemote", researchPath: "research/MediaRemote" ) + + static let userNotifications = SPKResearchTarget( + name: "UserNotifications and Notification Center", + summary: "Read-only Notification Center accessibility, process, framework, and notification-delivery research.", + documentationPath: "docs/frameworks/UserNotifications", + researchPath: "research/UserNotifications" + ) } diff --git a/Sources/spelunk/SPKMain.swift b/Sources/spelunk/SPKMain.swift index 930a04a..b4189d2 100644 --- a/Sources/spelunk/SPKMain.swift +++ b/Sources/spelunk/SPKMain.swift @@ -30,7 +30,7 @@ struct SPKMain { } private static func printTargets() { - for target in [SPKResearchTarget.messages, .phone, .mediaRemote] { + for target in [SPKResearchTarget.messages, .phone, .mediaRemote, .userNotifications] { print(target.name) print(target.summary) print("Docs: \(target.documentationPath)") diff --git a/Tests/SpelunkingKitTests/SPKResearchTargetTests.swift b/Tests/SpelunkingKitTests/SPKResearchTargetTests.swift index 7605f2d..f62bb0a 100644 --- a/Tests/SpelunkingKitTests/SPKResearchTargetTests.swift +++ b/Tests/SpelunkingKitTests/SPKResearchTargetTests.swift @@ -31,6 +31,15 @@ struct SPKResearchTargetTests { #expect(target.researchPath == "research/MediaRemote") } + @Test("UserNotifications target points at the persisted documentation and research directories") + func userNotificationsPaths() { + let target = SPKResearchTarget.userNotifications + + #expect(target.name == "UserNotifications and Notification Center") + #expect(target.documentationPath == "docs/frameworks/UserNotifications") + #expect(target.researchPath == "research/UserNotifications") + } + @Test("Notification Center probe explains an absent Accessibility grant") func notificationProbeUntrustedResult() throws { let encoded = try JSONEncoder().encode(.accessibilityNotTrusted as SPKNotificationCenterAccessibilityProbeResult) diff --git a/docs/README.md b/docs/README.md index 27e6326..8fe7e37 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,17 @@ Cross-target status: - [Messages and Phone research status](frameworks/messages-phone-status.md) +## Target Directory + +| Target | Status | Start Here | Safest First Command | +| --- | --- | --- | --- | +| MediaRemote | Baseline in progress | [MediaRemote overview](frameworks/MediaRemote/README.md) | `swift run mr-now-playing-probe` | +| Messages | Read-only baseline established | [Messages overview](frameworks/Messages/README.md) | `swift run spelunk targets` | +| Phone | Read-only baseline established | [Phone overview](frameworks/Phone/README.md) | `swift run spelunk targets` | +| UserNotifications | Read-only baseline established | [UserNotifications overview](frameworks/UserNotifications/README.md) | `swift run spelunk notifications --max-depth 6` | + +The commands above do not intentionally mutate media, message, call, notification, account, or system-service state. Some probes still load private frameworks, contact system daemons, or inspect Accessibility surfaces. Read the target overview for OS, permission, privacy, and runtime boundaries before collecting evidence. + Each target writeup should include: - scope diff --git a/docs/frameworks/Messages/README.md b/docs/frameworks/Messages/README.md index 37c5921..956f3e9 100644 --- a/docs/frameworks/Messages/README.md +++ b/docs/frameworks/Messages/README.md @@ -1,391 +1,33 @@ # Messages -## Scope +Read-only research into supported and private local Messages surfaces on macOS. The current baseline maps the public integration boundary, `Messages.app`, `chat.db` structure without row data, IM private frameworks, agents, notifications, hooks, and XPC ownership. -Research `Messages.app`, `com.apple.MobileSMS`, iMessage, SMS/RCS surfaces, `chat.db`, and related private frameworks, agents, daemons, XPC services, scripting hooks, URL schemes, storage, and supported extension APIs on macOS. +## Status -This is private, local-only reverse-engineering research. Do not treat private APIs, database access, dyld-cache symbols, app entitlements, AppleScript commands, or SIP-disabled behavior as public-release, App Store, customer-facing, or redistributed surfaces unless that separate analysis is explicitly opened. +Baseline established on macOS 26.5.2 (25F84) against the macOS 27.0 SDK. Generated interfaces, comparison against another OS build, and controlled event-delivery proof remain open. -## Environment +## Start Here -| Field | Value | -| --- | --- | -| Active OS | macOS 26.5.2 | -| Active OS build | 25F84 | -| Xcode path | `/Applications/Xcode-beta.app/Contents/Developer` | -| SDK comparison | macOS 27.0 SDK | -| SDK path | `$(xcrun --show-sdk-path --sdk macosx)` | -| Primary app path | `/System/Applications/Messages.app` | -| Bundle identifier | `com.apple.MobileSMS` | -| App version | `26.0` | -| App build | `1450.600.61.1.5` | +1. Read the [supported and private boundary](surfaces.md) before choosing an integration or experiment. +2. Use the [comprehensive baseline](baseline.md) for the environment, evidence checklist, initial findings, and open questions. +3. Follow the topic index below for focused conclusions. +4. Consult the [raw-evidence index](../../../research/Messages/README.md) only when reproducing or auditing a capture. -## Evidence Inventory +No command in this index sends a message or reads message rows. Some documented experiments inspect private frameworks, app metadata, daemon configuration, or database schema and can require Full Disk Access, Automation permission, or OS-specific private-framework availability. -- [x] Active app path -- [x] App bundle identifier, URL schemes, and scripting flags -- [x] App extension, plugin, URL, AppleScript, and intent surface inventory -- [x] App entitlement snapshot -- [x] AppleScript scripting dictionary -- [x] `chat.db` table and column inventory without row data -- [x] `chat.db` schema/index/trigger capture without row data -- [x] `chat.db` relationship, foreign-key, and trigger-lifecycle capture without row data -- [x] Active and SDK framework constellation inventory -- [x] App binary linked-library inventory -- [x] SDK `.tbd` symbol skim for `IMCore` -- [x] Filtered dyld shared cache export probe -- [x] Live dyld cache residency and interface-tooling boundary capture -- [x] LaunchAgent and XPC service inventory -- [x] XPC ownership and entitlement correlation capture -- [x] Public iPhoneOS 27.0 SDK header inventory for Messages, MessageUI, and Shared With You -- [x] Private `.tbd` notification and type-family inventory -- [x] Read-only Objective-C runtime metadata capture for IM private frameworks -- [x] Read-only Objective-C runtime metadata capture for IMD persistence, daemon, and MessagesKit surfaces -- [x] Focused hook, XPC, automation, query, and listener runtime inventory -- [x] Bounded app-open log observation -- [x] First-pass notification delivery classification from launchd and SDK symbol evidence -- [x] Bounded app-open notification observer baseline without payload values -- [ ] Generated Swift/Objective-C interfaces from dyld cache or SDK metadata -- [ ] OS comparison against another macOS build +## Topic Index -## Boundary Map +- [Surfaces](surfaces.md): supported extension and compose APIs, URL schemes, manifests, and the public/private boundary. +- [Storage](storage.md): `chat.db` schema, relationships, lifecycle metadata, and privacy limits. +- [Types](types.md): supported and private type families. +- [Symbols](symbols.md): SDK and live symbol evidence. +- [Agents](agents.md): apps, agents, daemons, plugins, and service ownership. +- [Runtime](runtime.md): Objective-C metadata and dyld-cache observations. +- [Hooks](hooks.md): automation, listener, query, callback, and interception surfaces. +- [Notifications](notifications.md): candidate names, delivery mechanisms, and observer evidence. +- [XPC ownership](xpc-ownership.md): launchd services, entitlements, clients, and authority boundaries. +- [Experiments](experiments.md): completed, blocked, and proposed research steps. -### Supported Public Surfaces +## Cross-Target Context -- Messages app extensions: `MSMessagesAppViewController`, `MSConversation`, `MSMessage`, and `MSSession`. -- Shared with You / collaboration metadata for app-owned shared state. -- App Intents and App Shortcuts for app-owned actions, not personal Messages access. -- `MFMessageComposeViewController` for user-visible compose/send flows. -- macOS Apple Events through `Messages.app` for limited local, user-controlled automation. - -These are not equivalent surfaces. A Messages extension lives inside visible user interaction. Shared with You carries app-owned collaboration metadata. App Intents expose app actions. Message UI presents a composer. Apple Events automate a local Mac app with permission and a small scripting dictionary. - -## Supported API Notes - -Verified from the iPhoneOS 27.0 SDK local headers. - -### Messages Framework - -`MSConversation` exposes: - -- participant identifiers scoped to this device: `localParticipantIdentifier` and `remoteParticipantIdentifiers` -- `selectedMessage` when the extension is invoked from a message in the transcript -- staging APIs: `insertMessage`, `insertSticker`, `insertText`, and `insertAttachment` -- send APIs: `sendMessage`, `sendSticker`, `sendText`, and `sendAttachment` - -Important boundary: the send APIs require the extension app to be visible and to have had a recent touch interaction since launch or the last send. This makes them user-present extension operations, not background send primitives. - -`MSMessagesAppViewController` exposes: - -- `activeConversation` -- presentation style and context -- lifecycle callbacks for becoming active and resigning active -- compact/expanded callbacks for message selection, message receipt, send start, send cancellation, and presentation transitions -- transcript presentation hooks such as `contentSizeThatFits`, message tint color, and message corner radius - -`MSMessage` exposes: - -- `session` for grouping message updates -- `isPending` -- sender participant identifier -- layout, URL payload, expiration, accessibility label, summary text, and send error - -Inference: Apple’s supported iMessage extension surface is a constrained UI-extension model for app-specific payloads and transcript UI, with app-owned state encoded through message URLs/layouts and updated through visible user interaction. - -### MessageUI - -`MFMessageComposeViewController` exposes: - -- capability checks: `canSendText`, `canSendSubject`, `canSendAttachments`, and `isSupportedAttachmentUTI` -- initial `recipients`, `body`, `subject`, attachments, and optional interactive `MSMessage` -- attachment APIs for file URLs and data -- `insertCollaborationItemProvider` for collaboration item providers -- delegate completion with `MessageComposeResultCancelled`, `MessageComposeResultSent`, or `MessageComposeResultFailed` - -Important boundary: `MessageComposeResultSent` means the user sent or queued the message; the actual delivery can still occur later when the device is able to send. - -The UPI category adds `setUPIVerificationCodeSendCompletion` behind the managed `com.apple.developer.upi-device-validation` entitlement. That completion reports actual SMS transmission only for that narrow managed-entitlement validation flow. - -### Shared With You Core - -`SWCollaborationMetadata` exposes: - -- globally unique `collaborationIdentifier` -- local `localIdentifier` -- app-owned `title` -- default and user-selected share options -- initiator handle/name fields used for local confirmation, not transmitted to recipients - -`SWStartCollaborationAction` carries collaboration metadata and can be fulfilled with a URL plus collaboration identifier. - -`SWUpdateCollaborationParticipantsAction` carries collaboration metadata plus added and removed `SWPersonIdentity` arrays. - -Inference: Shared With You collaboration APIs model app-owned shared objects and participant changes. They do not expose personal Messages history. - -### Private Local Surfaces - -- `~/Library/Messages/chat.db` and attachments. -- `IMCore`, `IMDPersistence`, `IMDaemonCore`, `IMFoundation`, `IMSharedUtilities`, and related IM private frameworks. -- `imagent`, `IMDPersistenceAgent`, transfer/transcoding agents, BlastDoor support, and Messages CloudKit sync components. -- Private entitlements such as `com.apple.private.imcore.imdpersistence.database-access`, `com.apple.private.security.storage.Messages`, and `com.apple.MessagesBlastDoorService` mach lookup. - -These are research surfaces only. They may explain how the system works locally, but they are not supported integration contracts. - -## App Manifest Notes - -Verified from `Messages.app/Contents/Info.plist`: - -- `AppleEventSupported` is `true`. -- `NSAppleScriptEnabled` is `true`. -- `OSAScriptingDefinition` is `Messages`. -- `NSPrincipalClass` is `SMSApplication`. -- URL schemes include `sms`, `sms-private`, `itms-messages`, `itms-messagess`, `imessage`, `iChat`, `Messages`, and `im`. -- The app advertises `NSUserActivityTypes` for `com.apple.Messages` and `com.apple.Messages.StateRestoration`. -- The app has a shortcut item with type `com.apple.mobilesms.newmessage`. -- The app declares privacy copy for contacts, location, microphone, camera, media library, SMS data, phone number, photos, call records, and focus status. - -## AppleScript Surface - -Verified with: - -```sh -sdef /System/Applications/Messages.app -``` - -The scripting dictionary exposes: - -- service types: `SMS`, `iMessage`, `RCS` -- transfer directions: `incoming`, `outgoing` -- transfer states: `preparing`, `waiting`, `transferring`, `finalizing`, `finished`, `failed` -- account connection states: `disconnecting`, `connected`, `connecting`, `disconnected` -- application elements: read-only `participants`, `accounts`, `fileTransfers`, and `chats` -- commands: `send`, `login`, and `logout` -- classes: `participant`, `account`, `chat`, and `file transfer` - -Important boundary: `send` can target a participant or chat, but the dictionary does not expose general historical search, direct `chat.db` rows, hidden account control, arbitrary message mutation, or remote/server-side iMessage operation. - -## Storage - -Verified table inventory from `~/Library/Messages/chat.db` without reading row data: - -- `_SqliteDatabaseProperties` -- `attachment` -- `chat` -- `chat_handle_join` -- `chat_lookup` -- `chat_message_join` -- `chat_recoverable_message_join` -- `chat_service` -- `deleted_messages` -- `handle` -- `index_state_metrics` -- `kvtable` -- `message` -- `message_attachment_join` -- `message_processing_task` -- `persistent_tasks` -- `recoverable_message_part` -- `scheduled_messages_pending_cloudkit_delete` -- `sync_chat_slice` -- `sync_deleted_attachments` -- `sync_deleted_chats` -- `sync_deleted_messages` -- `unsynced_removed_recoverable_messages` - -High-signal schema notes: - -- `message` is the main message record table. It includes identifiers, text/attributed body fields, service/account fields, delivery/read/send state, attachment cache state, reactions/replies/threading, expressive send style, CloudKit sync fields, safety/off-grid/satellite flags, scheduled send state, and indexing state. -- `chat` is the conversation table. It includes GUIDs, style/state, account and service names, display and group identifiers, archive/filter/recovery/deletion state, CloudKit sync fields, and pending review/blackhole flags. -- `handle` stores address/person identifiers and service/country fields. -- Join tables map chats to handles, chats to messages, messages to attachments, and chats to recoverable message parts. -- Foreign keys confirm cascade relationships for `chat_handle_join`, `chat_message_join`, `message_attachment_join`, `chat_lookup`, `chat_service`, `sync_chat_slice`, and recoverable-message joins. -- Sync and deleted-item tables indicate CloudKit-backed lifecycle bookkeeping. -- SQLite triggers enforce attachment-path cleanup, deleted GUID tracking, `sync_deleted_*` bookkeeping, orphan cleanup, plugin cleanup, cached room names, chat-service projection, failed-message metadata, and index-state metrics. -- `persistent_tasks` and `message_processing_task` indicate queued local work, but the first pass did not decode task flags or payload blobs. - -No message text, addresses, attachment names, or row counts were captured in this documentation pass. - -## Entitlement Notes - -Verified from `codesign -d --entitlements :- /System/Applications/Messages.app`. - -Notable areas: - -- storage: `com.apple.private.security.storage.Messages`, `MessagesMetaData`, and home-relative read-write exceptions for `/Library/Messages/`, `/Library/SMS/`, Messages caches, Biome, and media paths -- persistence: `com.apple.private.imcore.imdpersistence.database-access` -- IDS/Madrid: `com.apple.private.ids.messaging` values including `com.apple.madrid`, `com.apple.madrid.lite`, and relay values -- agents/services: mach lookup exceptions for `IMDPersistenceAgent`, `IMRemoteURLConnectionAgent`, `MessagesBlastDoorService`, `IMTranscoderAgent`, `identityservicesd`, `commcenter`, `telephonyutilities.callservicesdaemon`, `suggestd.messages`, and many collaboration/safety services -- CloudKit/social layer: CloudKit SPI, SocialLayer, file provider sharing, Shared With You/collaboration-related privileges -- TCC/privacy: address book, photos, media library, microphone, camera, location, focus status, communication notifications, time-sensitive and critical alerts -- safety/intelligence: communication safety, TextUnderstanding, summarization, translation, message-payload provider, and related private Biome streams - -Inference: Messages is a heavily privileged platform app coordinating local database access, IDS transport, content processing, CloudKit sync, safety checks, and local automation. Third-party code should not expect to reproduce this entitlement profile. - -## Framework And Agent Map - -Verified active framework/app inventory includes: - -- public: `Message.framework`, `InstantMessage.framework`, `TelephonyMessagingKit.framework` -- IM private: `IMCore`, `IMCorePipeline`, `IMDPersistence`, `IMDaemonCore`, `IMFoundation`, `IMSharedUtilities`, `IMSharedUI`, `IMTransferAgent`, `IMTransferAgentClient`, `IMTransferServices`, `IMTranscoding`, `IMTranscoderAgent`, `IMRCSTransfer`, `IMDMessageServices`, `IMAssistantCore`, `IMAVCore` -- Messages private: `MessagesKit`, `MessagesHelperKit`, `MessagesCloudSync`, `MessagesBlastDoorSupport`, `MessagesSettingsUI`, `MessageProtection`, `MessageSecurity`, `MessageUIMacHelper` -- Siri/agent adjacent: `SiriMessagesFlow`, `SiriMessagesFlowCommon`, `SiriMessagesUI`, `SiriMessageBus`, `SiriMessageTypes` - -The active app binary links to iOSSupport frameworks including `ChatKit`, `IMCore`, and `IMSharedUtilities`, plus macOS private frameworks including `IDSFoundation`, `FTServices`, and `FTClientServices`. - -Many private framework directories do not expose a direct on-disk Mach-O binary at the framework root on this macOS build. Their live implementations appear to be dyld shared cache residents or otherwise represented through framework metadata/stubs. Use dyld shared cache extraction for live symbol work. - -## Runtime Metadata Notes - -Verified by the local `spelunk objc-runtime` helper loading: - -- `/System/Library/PrivateFrameworks/IMCore.framework/IMCore` -- `/System/Library/PrivateFrameworks/IMSharedUtilities.framework/IMSharedUtilities` -- `/System/Library/PrivateFrameworks/IMFoundation.framework/IMFoundation` -- `/System/Library/PrivateFrameworks/IMDPersistence.framework/IMDPersistence` -- `/System/Library/PrivateFrameworks/IMDaemonCore.framework/IMDaemonCore` -- `/System/Library/PrivateFrameworks/MessagesKit.framework/MessagesKit` - -The narrow `IM*` capture produced 888 Objective-C classes and 150 Objective-C protocols on macOS 26.5.2. This is runtime metadata, not a generated public interface; method and property names are observed selectors/properties and still need behavior confirmation before being treated as stable contracts. - -The `IMD*`, `IMDaemon*`, and selected `CK*` MessagesKit capture produced 456 Objective-C classes and 105 Objective-C protocols. See `types.md` for the stable type-family inventory. - -High-signal observed class families: - -- account and identity: `IMAccount`, `IMAccountController`, `IMAccountUtilities`, `IMHandle`, `IMAddressBook`, `IMContactStore`, `IMBusinessNameManager` -- chat/message model: `IMChat`, `IMMessage`, `IMHandle`, `IMChatHistoryController`, `IMChatRegistry`, `IMChatItem`, `IMMessagePartChatItem`, `IMAssociatedMessageItem` -- attachments and transfer: `IMAttachment`, `IMAttachmentBlastdoor`, `IMFileTransfer`, preview generators, and attachment metadata classes -- persistence/indexing: `IMDDatabase`, `IMDDatabaseClient`, `IMDChatRecord`, `IMDMessageRecord`, `IMDAttachmentRecord`, `IMDCoreSpotlight*` indexers -- automation/hooks: `IMAutomation`, `IMAutomationMessageSend`, `IMAutomationBatchMessageOperations`, `IMCoreAutomationHook`, `IMCoreAutomationNotifications` -- collaboration and shared state: `IMCollaboration*`, `IMCloudKit*`, nickname, pinning, and sync-related classes - -Observed selector/property examples: - -- `IMAccount` exposes account state, aliases, relay capability, registration, login, service, block-list, buddy-list, profile, and `canSendMessages` properties/selectors. -- `IMChat` and adjacent chat classes expose local conversation state and history/controller relationships, but this capture does not prove a supported send or mutation contract outside the platform app. -- `IMD*` classes line up with the `chat.db` schema and Spotlight/CloudKit lifecycle tables, supporting the persistence-agent model described above. - -Inference: Messages' local architecture has a visible split between user/app model classes (`IMAccount`, `IMChat`, `IMMessage`, attachments), daemon/persistence classes (`IMD*`), and explicit automation/testing hooks (`IMAutomation*`, `IMCoreAutomation*`). The runtime metadata confirms these names exist in the active OS runtime; it does not establish that third-party processes can call them safely or with sufficient entitlements. - -See `runtime.md` for app-open log observations covering `imagent`, `IMDPersistenceAgent`, mark-read database calls, App Intents focus filtering, Spotlight indexing, and the message-entry UI responder. - -## Hook And XPC Notes - -See `hooks.md` for the focused hook-surface inventory generated from Objective-C runtime metadata. - -High-signal private hook families include: - -- `IMDaemonChatSendMessageProtocol`, with private selectors for send, edit, scheduled-message, group-photo, attachment resend, junk-report, and translation operations -- `IMDaemonChatModifyReadStateProtocol`, with mark-read, mark-saved, expressive-send, and notify-recipient selectors -- `IMDaemonAutomationProtocol`, with explicit automation, simulation, replay, and test selectors -- `IMDMessageQueries`, `IMDChatQueries`, and `IMDNotificationQueries`, with persistence/query selectors that line up with `chat.db`, unread counts, index state, and SharePlay notification state -- listener and routing classes such as `IMDIncomingClientConnectionListener`, `IMDPersistenceServiceListener`, `IMDBackgroundMessagingAPIListener`, `IMDaemonCore.ClientConnection`, and `IMDaemonCore.XPCClientConnectionRouteProvider` - -Inference: Messages' private hooks are protocol and daemon oriented. They are better evidence for Apple-client-to-daemon architecture than for a supported local integration path. - -## SDK Symbol Notes - -Verified from the macOS 27.0 SDK `IMCore.tbd`: - -- `IMCore` reexports `InstantMessage` and `IMFoundation`. -- The SDK includes many Swift symbols under the `IMCore.ImportExport` namespace. -- High-signal demangled symbol families include attachment, participant, and conversation import/export iterators, async batches, export statistics, progress reporting, and CloudKit sync completion state. - -Inference: the SDK-visible `IMCore` export surface includes modern Swift import/export plumbing for records, attachments, participants, and conversations, not only legacy Objective-C IM types. - -Demangled `IMCore` families from the macOS 27.0 SDK include: - -- `ImportExportRecordExportIterating` -- `ImportExportProgressReporting` -- `ImportExport.AttachmentExportIterator` -- `ImportExport.ParticipantExportIterator` -- `ImportExport.ConversationExportIterator` -- `ImportExport.ArchiveImportIterator` -- `ImportExport.Attachment`, `Participant`, and `Conversation` batch types -- `ImportExport.ExportOptions` -- `ImportExport.ExportStatistics` -- `ImportExport.RecordCounts` -- `ImportExport.AttachmentDownloader` -- `ImportExport.MessageExportExclusionFilter` - -Observed `MessageExportExclusionFilter` cases include promotional, transactional, balloon plugins, junk, system, chat bot, default, deleted, expired, all cases, and business. - -## Dyld Shared Cache Notes - -Verified with: - -```sh -dyld_info -exports -objc -all_dyld_cache -``` - -The active arm64e shared cache is split under `/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/`. - -Observed export/symbol hints: - -- `IMCoreAttachmentBlastdoorErrorDomain` -- `IMCoreDuetLogHandle` -- `IMCoreSpotlightIndexReasonIsCritical` -- `IMCoreSpotlightIndexReasonIsIncomingMessage` -- `IMCouldBeChatBotKey` -- `IMIsRunningInIMDPersistenceAgent` -- `IMIsRunningInImagent` -- `IMiMessagePrivacyPolicyNotification` -- `MessageServiceLogHandle` -- `NSStringFromIMCoreSpotlightIndexReason` -- `NSStringFromIMPersistentTaskExecutorStatus` -- `NSStringFromIMPersistentTaskLane` -- `IMCoreAutomationNotifications` -- `IMCoreRecentsMetadataBuilder` -- `IMCoreSpotlightUtilities` - -Boundary: `dyld_info` reported that it cannot print live Objective-C metadata from dylibs in the dyld shared cache. A later class/protocol/selector pass needs a different extraction path or a controlled runtime helper. - -## Launchd And XPC - -Verified LaunchAgents: - -| Label | Program | High-signal services or triggers | -| --- | --- | --- | -| `com.apple.imagent` | `IMCore.framework/imagent.app` | Mach services for APS/imagent, Messages notifications delegates, Spotlight messages, incoming-call-filter, Madrid IDS wake; launch events for AuthKit user info and `com.apple.private.IMCore.LoggedIntoHSA2` | -| `com.apple.imautomatichistorydeletionagent` | `IMDPersistence.framework/IMAutomaticHistoryDeletionAgent.app` | daily xpc activity plus `com.apple.imautomatichistorydeletionagent.prefchange` | -| `com.apple.imcore.imtransferagent` | `IMTransferServices.framework/IMTransferAgent.app` | Mach service `com.apple.imtransferservices.IMTransferAgent`; IDS transfer launch notification | - -Verified XPC services: - -| Bundle identifier | Visible name | Notes | -| --- | --- | --- | -| `com.apple.imdmessageservices.IMDMessageServicesAgent` | Message Services Agent | application XPC service | -| `com.apple.imdpersistence.IMDPersistenceAgent` | Messages Database Agent | user XPC service with explicit Apple-signed allowed-client list | -| `com.apple.imtranscoding.IMTranscoderAgent` | Messages Transcoding Agent | application XPC service with GPU access | - -`IMDPersistenceAgent.xpc` allowed clients include Apple-signed `MobileSMS.spotlight`, `imagent`, `IMDMessageServicesAgent`, Safari variants, `iChat`, `AddressBook.FaceTimeService`, `imtool`, `assistantd`, `ContactsAgent`, `messages.AssistantExtension`, `IMAutomaticHistoryDeletionAgent`, `messages.StorageManagementExtension`, Control Center, Photos, Game Center, FaceTime, Finder, SocialLayer, CoreDuet, People, Ask To, Suggestd, OmniSearch, diagnostics, and internal incubation tools. - -Inference: database access is brokered through a privileged XPC service with a tight Apple-signed client allowlist, not a generic local IPC endpoint for third-party callers. - -## Open Questions - -- Which live dyld-cache classes and methods back `IMChat`, `IMHandle`, `IMAccount`, and scripting bridge keys on macOS 26.5.2? -- Which XPC messages are exchanged between `Messages.app`, `imagent`, `IMDPersistenceAgent`, `MessagesBlastDoorService`, and transfer/transcoding agents? -- Which `chat.db` task flags and message state integer values map to named IMCore constants? -- Which fields are stable across macOS 26.5.2 and macOS 27.0 SDK assumptions? -- Which remaining unclassified notification constants are posted in-process, through distributed notification center, through Darwin notify, or only used as local symbols? -- Which Apple Events operations require app launch, explicit Automation consent, or foreground user context? - -## References - -- `docs/frameworks/messages-phone-status.md` -- `research/Messages/README.md` -- `docs/frameworks/Messages/surfaces.md` -- `docs/frameworks/Messages/agents.md` -- `docs/frameworks/Messages/xpc-ownership.md` -- `docs/frameworks/Messages/storage.md` -- `docs/frameworks/Messages/symbols.md` -- `docs/frameworks/Messages/notifications.md` -- `docs/frameworks/Messages/types.md` -- `docs/frameworks/Messages/hooks.md` -- `docs/frameworks/Messages/runtime.md` -- `docs/frameworks/Messages/experiments.md` -- Apple Developer Documentation: [Messages framework](https://developer.apple.com/documentation/messages) -- Apple Developer Documentation: [Shared with You framework](https://developer.apple.com/documentation/sharedwithyou) -- Apple Developer Documentation: [Shared with You Core `SWCollaborationMetadata`](https://developer.apple.com/documentation/sharedwithyoucore/swcollaborationmetadata) -- Apple Developer Documentation: [MessageUI `MFMessageComposeViewController`](https://developer.apple.com/documentation/messageui/mfmessagecomposeviewcontroller) -- Apple Developer Documentation: [App Intents framework](https://developer.apple.com/documentation/appintents) +Messages and Phone share several communication-service boundaries. Use the [combined status map](../messages-phone-status.md) when a finding crosses both targets. diff --git a/docs/frameworks/Messages/baseline.md b/docs/frameworks/Messages/baseline.md new file mode 100644 index 0000000..81effa7 --- /dev/null +++ b/docs/frameworks/Messages/baseline.md @@ -0,0 +1,391 @@ +# Messages Baseline + +## Scope + +Research `Messages.app`, `com.apple.MobileSMS`, iMessage, SMS/RCS surfaces, `chat.db`, and related private frameworks, agents, daemons, XPC services, scripting hooks, URL schemes, storage, and supported extension APIs on macOS. + +This is private, local-only reverse-engineering research. Do not treat private APIs, database access, dyld-cache symbols, app entitlements, AppleScript commands, or SIP-disabled behavior as public-release, App Store, customer-facing, or redistributed surfaces unless that separate analysis is explicitly opened. + +## Environment + +| Field | Value | +| --- | --- | +| Active OS | macOS 26.5.2 | +| Active OS build | 25F84 | +| Xcode path | `/Applications/Xcode-beta.app/Contents/Developer` | +| SDK comparison | macOS 27.0 SDK | +| SDK path | `$(xcrun --show-sdk-path --sdk macosx)` | +| Primary app path | `/System/Applications/Messages.app` | +| Bundle identifier | `com.apple.MobileSMS` | +| App version | `26.0` | +| App build | `1450.600.61.1.5` | + +## Evidence Inventory + +- [x] Active app path +- [x] App bundle identifier, URL schemes, and scripting flags +- [x] App extension, plugin, URL, AppleScript, and intent surface inventory +- [x] App entitlement snapshot +- [x] AppleScript scripting dictionary +- [x] `chat.db` table and column inventory without row data +- [x] `chat.db` schema/index/trigger capture without row data +- [x] `chat.db` relationship, foreign-key, and trigger-lifecycle capture without row data +- [x] Active and SDK framework constellation inventory +- [x] App binary linked-library inventory +- [x] SDK `.tbd` symbol skim for `IMCore` +- [x] Filtered dyld shared cache export probe +- [x] Live dyld cache residency and interface-tooling boundary capture +- [x] LaunchAgent and XPC service inventory +- [x] XPC ownership and entitlement correlation capture +- [x] Public iPhoneOS 27.0 SDK header inventory for Messages, MessageUI, and Shared With You +- [x] Private `.tbd` notification and type-family inventory +- [x] Read-only Objective-C runtime metadata capture for IM private frameworks +- [x] Read-only Objective-C runtime metadata capture for IMD persistence, daemon, and MessagesKit surfaces +- [x] Focused hook, XPC, automation, query, and listener runtime inventory +- [x] Bounded app-open log observation +- [x] First-pass notification delivery classification from launchd and SDK symbol evidence +- [x] Bounded app-open notification observer baseline without payload values +- [ ] Generated Swift/Objective-C interfaces from dyld cache or SDK metadata +- [ ] OS comparison against another macOS build + +## Boundary Map + +### Supported Public Surfaces + +- Messages app extensions: `MSMessagesAppViewController`, `MSConversation`, `MSMessage`, and `MSSession`. +- Shared with You / collaboration metadata for app-owned shared state. +- App Intents and App Shortcuts for app-owned actions, not personal Messages access. +- `MFMessageComposeViewController` for user-visible compose/send flows. +- macOS Apple Events through `Messages.app` for limited local, user-controlled automation. + +These are not equivalent surfaces. A Messages extension lives inside visible user interaction. Shared with You carries app-owned collaboration metadata. App Intents expose app actions. Message UI presents a composer. Apple Events automate a local Mac app with permission and a small scripting dictionary. + +## Supported API Notes + +Verified from the iPhoneOS 27.0 SDK local headers. + +### Messages Framework + +`MSConversation` exposes: + +- participant identifiers scoped to this device: `localParticipantIdentifier` and `remoteParticipantIdentifiers` +- `selectedMessage` when the extension is invoked from a message in the transcript +- staging APIs: `insertMessage`, `insertSticker`, `insertText`, and `insertAttachment` +- send APIs: `sendMessage`, `sendSticker`, `sendText`, and `sendAttachment` + +Important boundary: the send APIs require the extension app to be visible and to have had a recent touch interaction since launch or the last send. This makes them user-present extension operations, not background send primitives. + +`MSMessagesAppViewController` exposes: + +- `activeConversation` +- presentation style and context +- lifecycle callbacks for becoming active and resigning active +- compact/expanded callbacks for message selection, message receipt, send start, send cancellation, and presentation transitions +- transcript presentation hooks such as `contentSizeThatFits`, message tint color, and message corner radius + +`MSMessage` exposes: + +- `session` for grouping message updates +- `isPending` +- sender participant identifier +- layout, URL payload, expiration, accessibility label, summary text, and send error + +Inference: Apple’s supported iMessage extension surface is a constrained UI-extension model for app-specific payloads and transcript UI, with app-owned state encoded through message URLs/layouts and updated through visible user interaction. + +### MessageUI + +`MFMessageComposeViewController` exposes: + +- capability checks: `canSendText`, `canSendSubject`, `canSendAttachments`, and `isSupportedAttachmentUTI` +- initial `recipients`, `body`, `subject`, attachments, and optional interactive `MSMessage` +- attachment APIs for file URLs and data +- `insertCollaborationItemProvider` for collaboration item providers +- delegate completion with `MessageComposeResultCancelled`, `MessageComposeResultSent`, or `MessageComposeResultFailed` + +Important boundary: `MessageComposeResultSent` means the user sent or queued the message; the actual delivery can still occur later when the device is able to send. + +The UPI category adds `setUPIVerificationCodeSendCompletion` behind the managed `com.apple.developer.upi-device-validation` entitlement. That completion reports actual SMS transmission only for that narrow managed-entitlement validation flow. + +### Shared With You Core + +`SWCollaborationMetadata` exposes: + +- globally unique `collaborationIdentifier` +- local `localIdentifier` +- app-owned `title` +- default and user-selected share options +- initiator handle/name fields used for local confirmation, not transmitted to recipients + +`SWStartCollaborationAction` carries collaboration metadata and can be fulfilled with a URL plus collaboration identifier. + +`SWUpdateCollaborationParticipantsAction` carries collaboration metadata plus added and removed `SWPersonIdentity` arrays. + +Inference: Shared With You collaboration APIs model app-owned shared objects and participant changes. They do not expose personal Messages history. + +### Private Local Surfaces + +- `~/Library/Messages/chat.db` and attachments. +- `IMCore`, `IMDPersistence`, `IMDaemonCore`, `IMFoundation`, `IMSharedUtilities`, and related IM private frameworks. +- `imagent`, `IMDPersistenceAgent`, transfer/transcoding agents, BlastDoor support, and Messages CloudKit sync components. +- Private entitlements such as `com.apple.private.imcore.imdpersistence.database-access`, `com.apple.private.security.storage.Messages`, and `com.apple.MessagesBlastDoorService` mach lookup. + +These are research surfaces only. They may explain how the system works locally, but they are not supported integration contracts. + +## App Manifest Notes + +Verified from `Messages.app/Contents/Info.plist`: + +- `AppleEventSupported` is `true`. +- `NSAppleScriptEnabled` is `true`. +- `OSAScriptingDefinition` is `Messages`. +- `NSPrincipalClass` is `SMSApplication`. +- URL schemes include `sms`, `sms-private`, `itms-messages`, `itms-messagess`, `imessage`, `iChat`, `Messages`, and `im`. +- The app advertises `NSUserActivityTypes` for `com.apple.Messages` and `com.apple.Messages.StateRestoration`. +- The app has a shortcut item with type `com.apple.mobilesms.newmessage`. +- The app declares privacy copy for contacts, location, microphone, camera, media library, SMS data, phone number, photos, call records, and focus status. + +## AppleScript Surface + +Verified with: + +```sh +sdef /System/Applications/Messages.app +``` + +The scripting dictionary exposes: + +- service types: `SMS`, `iMessage`, `RCS` +- transfer directions: `incoming`, `outgoing` +- transfer states: `preparing`, `waiting`, `transferring`, `finalizing`, `finished`, `failed` +- account connection states: `disconnecting`, `connected`, `connecting`, `disconnected` +- application elements: read-only `participants`, `accounts`, `fileTransfers`, and `chats` +- commands: `send`, `login`, and `logout` +- classes: `participant`, `account`, `chat`, and `file transfer` + +Important boundary: `send` can target a participant or chat, but the dictionary does not expose general historical search, direct `chat.db` rows, hidden account control, arbitrary message mutation, or remote/server-side iMessage operation. + +## Storage + +Verified table inventory from `~/Library/Messages/chat.db` without reading row data: + +- `_SqliteDatabaseProperties` +- `attachment` +- `chat` +- `chat_handle_join` +- `chat_lookup` +- `chat_message_join` +- `chat_recoverable_message_join` +- `chat_service` +- `deleted_messages` +- `handle` +- `index_state_metrics` +- `kvtable` +- `message` +- `message_attachment_join` +- `message_processing_task` +- `persistent_tasks` +- `recoverable_message_part` +- `scheduled_messages_pending_cloudkit_delete` +- `sync_chat_slice` +- `sync_deleted_attachments` +- `sync_deleted_chats` +- `sync_deleted_messages` +- `unsynced_removed_recoverable_messages` + +High-signal schema notes: + +- `message` is the main message record table. It includes identifiers, text/attributed body fields, service/account fields, delivery/read/send state, attachment cache state, reactions/replies/threading, expressive send style, CloudKit sync fields, safety/off-grid/satellite flags, scheduled send state, and indexing state. +- `chat` is the conversation table. It includes GUIDs, style/state, account and service names, display and group identifiers, archive/filter/recovery/deletion state, CloudKit sync fields, and pending review/blackhole flags. +- `handle` stores address/person identifiers and service/country fields. +- Join tables map chats to handles, chats to messages, messages to attachments, and chats to recoverable message parts. +- Foreign keys confirm cascade relationships for `chat_handle_join`, `chat_message_join`, `message_attachment_join`, `chat_lookup`, `chat_service`, `sync_chat_slice`, and recoverable-message joins. +- Sync and deleted-item tables indicate CloudKit-backed lifecycle bookkeeping. +- SQLite triggers enforce attachment-path cleanup, deleted GUID tracking, `sync_deleted_*` bookkeeping, orphan cleanup, plugin cleanup, cached room names, chat-service projection, failed-message metadata, and index-state metrics. +- `persistent_tasks` and `message_processing_task` indicate queued local work, but the first pass did not decode task flags or payload blobs. + +No message text, addresses, attachment names, or row counts were captured in this documentation pass. + +## Entitlement Notes + +Verified from `codesign -d --entitlements :- /System/Applications/Messages.app`. + +Notable areas: + +- storage: `com.apple.private.security.storage.Messages`, `MessagesMetaData`, and home-relative read-write exceptions for `/Library/Messages/`, `/Library/SMS/`, Messages caches, Biome, and media paths +- persistence: `com.apple.private.imcore.imdpersistence.database-access` +- IDS/Madrid: `com.apple.private.ids.messaging` values including `com.apple.madrid`, `com.apple.madrid.lite`, and relay values +- agents/services: mach lookup exceptions for `IMDPersistenceAgent`, `IMRemoteURLConnectionAgent`, `MessagesBlastDoorService`, `IMTranscoderAgent`, `identityservicesd`, `commcenter`, `telephonyutilities.callservicesdaemon`, `suggestd.messages`, and many collaboration/safety services +- CloudKit/social layer: CloudKit SPI, SocialLayer, file provider sharing, Shared With You/collaboration-related privileges +- TCC/privacy: address book, photos, media library, microphone, camera, location, focus status, communication notifications, time-sensitive and critical alerts +- safety/intelligence: communication safety, TextUnderstanding, summarization, translation, message-payload provider, and related private Biome streams + +Inference: Messages is a heavily privileged platform app coordinating local database access, IDS transport, content processing, CloudKit sync, safety checks, and local automation. Third-party code should not expect to reproduce this entitlement profile. + +## Framework And Agent Map + +Verified active framework/app inventory includes: + +- public: `Message.framework`, `InstantMessage.framework`, `TelephonyMessagingKit.framework` +- IM private: `IMCore`, `IMCorePipeline`, `IMDPersistence`, `IMDaemonCore`, `IMFoundation`, `IMSharedUtilities`, `IMSharedUI`, `IMTransferAgent`, `IMTransferAgentClient`, `IMTransferServices`, `IMTranscoding`, `IMTranscoderAgent`, `IMRCSTransfer`, `IMDMessageServices`, `IMAssistantCore`, `IMAVCore` +- Messages private: `MessagesKit`, `MessagesHelperKit`, `MessagesCloudSync`, `MessagesBlastDoorSupport`, `MessagesSettingsUI`, `MessageProtection`, `MessageSecurity`, `MessageUIMacHelper` +- Siri/agent adjacent: `SiriMessagesFlow`, `SiriMessagesFlowCommon`, `SiriMessagesUI`, `SiriMessageBus`, `SiriMessageTypes` + +The active app binary links to iOSSupport frameworks including `ChatKit`, `IMCore`, and `IMSharedUtilities`, plus macOS private frameworks including `IDSFoundation`, `FTServices`, and `FTClientServices`. + +Many private framework directories do not expose a direct on-disk Mach-O binary at the framework root on this macOS build. Their live implementations appear to be dyld shared cache residents or otherwise represented through framework metadata/stubs. Use dyld shared cache extraction for live symbol work. + +## Runtime Metadata Notes + +Verified by the local `spelunk objc-runtime` helper loading: + +- `/System/Library/PrivateFrameworks/IMCore.framework/IMCore` +- `/System/Library/PrivateFrameworks/IMSharedUtilities.framework/IMSharedUtilities` +- `/System/Library/PrivateFrameworks/IMFoundation.framework/IMFoundation` +- `/System/Library/PrivateFrameworks/IMDPersistence.framework/IMDPersistence` +- `/System/Library/PrivateFrameworks/IMDaemonCore.framework/IMDaemonCore` +- `/System/Library/PrivateFrameworks/MessagesKit.framework/MessagesKit` + +The narrow `IM*` capture produced 888 Objective-C classes and 150 Objective-C protocols on macOS 26.5.2. This is runtime metadata, not a generated public interface; method and property names are observed selectors/properties and still need behavior confirmation before being treated as stable contracts. + +The `IMD*`, `IMDaemon*`, and selected `CK*` MessagesKit capture produced 456 Objective-C classes and 105 Objective-C protocols. See `types.md` for the stable type-family inventory. + +High-signal observed class families: + +- account and identity: `IMAccount`, `IMAccountController`, `IMAccountUtilities`, `IMHandle`, `IMAddressBook`, `IMContactStore`, `IMBusinessNameManager` +- chat/message model: `IMChat`, `IMMessage`, `IMHandle`, `IMChatHistoryController`, `IMChatRegistry`, `IMChatItem`, `IMMessagePartChatItem`, `IMAssociatedMessageItem` +- attachments and transfer: `IMAttachment`, `IMAttachmentBlastdoor`, `IMFileTransfer`, preview generators, and attachment metadata classes +- persistence/indexing: `IMDDatabase`, `IMDDatabaseClient`, `IMDChatRecord`, `IMDMessageRecord`, `IMDAttachmentRecord`, `IMDCoreSpotlight*` indexers +- automation/hooks: `IMAutomation`, `IMAutomationMessageSend`, `IMAutomationBatchMessageOperations`, `IMCoreAutomationHook`, `IMCoreAutomationNotifications` +- collaboration and shared state: `IMCollaboration*`, `IMCloudKit*`, nickname, pinning, and sync-related classes + +Observed selector/property examples: + +- `IMAccount` exposes account state, aliases, relay capability, registration, login, service, block-list, buddy-list, profile, and `canSendMessages` properties/selectors. +- `IMChat` and adjacent chat classes expose local conversation state and history/controller relationships, but this capture does not prove a supported send or mutation contract outside the platform app. +- `IMD*` classes line up with the `chat.db` schema and Spotlight/CloudKit lifecycle tables, supporting the persistence-agent model described above. + +Inference: Messages' local architecture has a visible split between user/app model classes (`IMAccount`, `IMChat`, `IMMessage`, attachments), daemon/persistence classes (`IMD*`), and explicit automation/testing hooks (`IMAutomation*`, `IMCoreAutomation*`). The runtime metadata confirms these names exist in the active OS runtime; it does not establish that third-party processes can call them safely or with sufficient entitlements. + +See `runtime.md` for app-open log observations covering `imagent`, `IMDPersistenceAgent`, mark-read database calls, App Intents focus filtering, Spotlight indexing, and the message-entry UI responder. + +## Hook And XPC Notes + +See `hooks.md` for the focused hook-surface inventory generated from Objective-C runtime metadata. + +High-signal private hook families include: + +- `IMDaemonChatSendMessageProtocol`, with private selectors for send, edit, scheduled-message, group-photo, attachment resend, junk-report, and translation operations +- `IMDaemonChatModifyReadStateProtocol`, with mark-read, mark-saved, expressive-send, and notify-recipient selectors +- `IMDaemonAutomationProtocol`, with explicit automation, simulation, replay, and test selectors +- `IMDMessageQueries`, `IMDChatQueries`, and `IMDNotificationQueries`, with persistence/query selectors that line up with `chat.db`, unread counts, index state, and SharePlay notification state +- listener and routing classes such as `IMDIncomingClientConnectionListener`, `IMDPersistenceServiceListener`, `IMDBackgroundMessagingAPIListener`, `IMDaemonCore.ClientConnection`, and `IMDaemonCore.XPCClientConnectionRouteProvider` + +Inference: Messages' private hooks are protocol and daemon oriented. They are better evidence for Apple-client-to-daemon architecture than for a supported local integration path. + +## SDK Symbol Notes + +Verified from the macOS 27.0 SDK `IMCore.tbd`: + +- `IMCore` reexports `InstantMessage` and `IMFoundation`. +- The SDK includes many Swift symbols under the `IMCore.ImportExport` namespace. +- High-signal demangled symbol families include attachment, participant, and conversation import/export iterators, async batches, export statistics, progress reporting, and CloudKit sync completion state. + +Inference: the SDK-visible `IMCore` export surface includes modern Swift import/export plumbing for records, attachments, participants, and conversations, not only legacy Objective-C IM types. + +Demangled `IMCore` families from the macOS 27.0 SDK include: + +- `ImportExportRecordExportIterating` +- `ImportExportProgressReporting` +- `ImportExport.AttachmentExportIterator` +- `ImportExport.ParticipantExportIterator` +- `ImportExport.ConversationExportIterator` +- `ImportExport.ArchiveImportIterator` +- `ImportExport.Attachment`, `Participant`, and `Conversation` batch types +- `ImportExport.ExportOptions` +- `ImportExport.ExportStatistics` +- `ImportExport.RecordCounts` +- `ImportExport.AttachmentDownloader` +- `ImportExport.MessageExportExclusionFilter` + +Observed `MessageExportExclusionFilter` cases include promotional, transactional, balloon plugins, junk, system, chat bot, default, deleted, expired, all cases, and business. + +## Dyld Shared Cache Notes + +Verified with: + +```sh +dyld_info -exports -objc -all_dyld_cache +``` + +The active arm64e shared cache is split under `/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/`. + +Observed export/symbol hints: + +- `IMCoreAttachmentBlastdoorErrorDomain` +- `IMCoreDuetLogHandle` +- `IMCoreSpotlightIndexReasonIsCritical` +- `IMCoreSpotlightIndexReasonIsIncomingMessage` +- `IMCouldBeChatBotKey` +- `IMIsRunningInIMDPersistenceAgent` +- `IMIsRunningInImagent` +- `IMiMessagePrivacyPolicyNotification` +- `MessageServiceLogHandle` +- `NSStringFromIMCoreSpotlightIndexReason` +- `NSStringFromIMPersistentTaskExecutorStatus` +- `NSStringFromIMPersistentTaskLane` +- `IMCoreAutomationNotifications` +- `IMCoreRecentsMetadataBuilder` +- `IMCoreSpotlightUtilities` + +Boundary: `dyld_info` reported that it cannot print live Objective-C metadata from dylibs in the dyld shared cache. A later class/protocol/selector pass needs a different extraction path or a controlled runtime helper. + +## Launchd And XPC + +Verified LaunchAgents: + +| Label | Program | High-signal services or triggers | +| --- | --- | --- | +| `com.apple.imagent` | `IMCore.framework/imagent.app` | Mach services for APS/imagent, Messages notifications delegates, Spotlight messages, incoming-call-filter, Madrid IDS wake; launch events for AuthKit user info and `com.apple.private.IMCore.LoggedIntoHSA2` | +| `com.apple.imautomatichistorydeletionagent` | `IMDPersistence.framework/IMAutomaticHistoryDeletionAgent.app` | daily xpc activity plus `com.apple.imautomatichistorydeletionagent.prefchange` | +| `com.apple.imcore.imtransferagent` | `IMTransferServices.framework/IMTransferAgent.app` | Mach service `com.apple.imtransferservices.IMTransferAgent`; IDS transfer launch notification | + +Verified XPC services: + +| Bundle identifier | Visible name | Notes | +| --- | --- | --- | +| `com.apple.imdmessageservices.IMDMessageServicesAgent` | Message Services Agent | application XPC service | +| `com.apple.imdpersistence.IMDPersistenceAgent` | Messages Database Agent | user XPC service with explicit Apple-signed allowed-client list | +| `com.apple.imtranscoding.IMTranscoderAgent` | Messages Transcoding Agent | application XPC service with GPU access | + +`IMDPersistenceAgent.xpc` allowed clients include Apple-signed `MobileSMS.spotlight`, `imagent`, `IMDMessageServicesAgent`, Safari variants, `iChat`, `AddressBook.FaceTimeService`, `imtool`, `assistantd`, `ContactsAgent`, `messages.AssistantExtension`, `IMAutomaticHistoryDeletionAgent`, `messages.StorageManagementExtension`, Control Center, Photos, Game Center, FaceTime, Finder, SocialLayer, CoreDuet, People, Ask To, Suggestd, OmniSearch, diagnostics, and internal incubation tools. + +Inference: database access is brokered through a privileged XPC service with a tight Apple-signed client allowlist, not a generic local IPC endpoint for third-party callers. + +## Open Questions + +- Which live dyld-cache classes and methods back `IMChat`, `IMHandle`, `IMAccount`, and scripting bridge keys on macOS 26.5.2? +- Which XPC messages are exchanged between `Messages.app`, `imagent`, `IMDPersistenceAgent`, `MessagesBlastDoorService`, and transfer/transcoding agents? +- Which `chat.db` task flags and message state integer values map to named IMCore constants? +- Which fields are stable across macOS 26.5.2 and macOS 27.0 SDK assumptions? +- Which remaining unclassified notification constants are posted in-process, through distributed notification center, through Darwin notify, or only used as local symbols? +- Which Apple Events operations require app launch, explicit Automation consent, or foreground user context? + +## References + +- `docs/frameworks/messages-phone-status.md` +- `research/Messages/README.md` +- `docs/frameworks/Messages/surfaces.md` +- `docs/frameworks/Messages/agents.md` +- `docs/frameworks/Messages/xpc-ownership.md` +- `docs/frameworks/Messages/storage.md` +- `docs/frameworks/Messages/symbols.md` +- `docs/frameworks/Messages/notifications.md` +- `docs/frameworks/Messages/types.md` +- `docs/frameworks/Messages/hooks.md` +- `docs/frameworks/Messages/runtime.md` +- `docs/frameworks/Messages/experiments.md` +- Apple Developer Documentation: [Messages framework](https://developer.apple.com/documentation/messages) +- Apple Developer Documentation: [Shared with You framework](https://developer.apple.com/documentation/sharedwithyou) +- Apple Developer Documentation: [Shared with You Core `SWCollaborationMetadata`](https://developer.apple.com/documentation/sharedwithyoucore/swcollaborationmetadata) +- Apple Developer Documentation: [MessageUI `MFMessageComposeViewController`](https://developer.apple.com/documentation/messageui/mfmessagecomposeviewcontroller) +- Apple Developer Documentation: [App Intents framework](https://developer.apple.com/documentation/appintents) diff --git a/docs/frameworks/Phone/README.md b/docs/frameworks/Phone/README.md index b4b00cc..ccb8c69 100644 --- a/docs/frameworks/Phone/README.md +++ b/docs/frameworks/Phone/README.md @@ -1,378 +1,33 @@ # Phone -## Scope +Read-only research into supported and private local Phone and calling surfaces on macOS. The current baseline maps public call APIs, `Phone.app`, call-history structure without row data, telephony private frameworks, agents, notifications, hooks, and XPC ownership. -Research `Phone.app`, `com.apple.mobilephone`, call history, telephony/call services, Phone App Intents, FaceTime-adjacent call surfaces, URL schemes, private frameworks, daemons, XPC services, storage, hooks, and supported public call APIs on macOS. +## Status -This is private, local-only reverse-engineering research. Do not treat private APIs, entitlements, call-history stores, TelephonyUtilities services, or SIP-disabled behavior as public-release, App Store, customer-facing, or redistributed surfaces unless that separate analysis is explicitly opened. +Baseline established on macOS 26.5.2 (25F84) against the macOS 27.0 SDK. Generated interfaces, comparison against another OS build, and controlled call-event proof remain open. -## Environment +## Start Here -| Field | Value | -| --- | --- | -| Active OS | macOS 26.5.2 | -| Active OS build | 25F84 | -| Xcode path | `/Applications/Xcode-beta.app/Contents/Developer` | -| SDK comparison | macOS 27.0 SDK | -| SDK path | `$(xcrun --show-sdk-path --sdk macosx)` | -| Primary app path | `/System/Applications/Phone.app` | -| Bundle identifier | `com.apple.mobilephone` | -| App version | `1.0` | -| App build | `1` | +1. Read the [supported and private boundary](surfaces.md) before choosing an integration or experiment. +2. Use the [comprehensive baseline](baseline.md) for the environment, evidence checklist, initial findings, and open questions. +3. Follow the topic index below for focused conclusions. +4. Consult the [raw-evidence index](../../../research/Phone/README.md) only when reproducing or auditing a capture. -## Evidence Inventory +No command in this index initiates a call or reads call-history rows. Some documented experiments inspect private frameworks, app metadata, daemon configuration, or database schema and can require Full Disk Access, TCC permission, entitlements, or OS-specific private-framework availability. -- [x] Active app path -- [x] App bundle identifier and URL schemes -- [x] App extension, plugin, URL, AppleScript, and intent surface inventory -- [x] App entitlement snapshot -- [x] Confirm no AppleScript dictionary via `sdef` -- [x] Active and SDK framework constellation inventory -- [x] App binary linked-library inventory -- [x] SDK `.tbd` symbol skim for `CallsXPC`, `CallsPersistence`, and `PhoneAppIntents` -- [x] Filtered dyld shared cache export probe -- [x] Live dyld cache residency and interface-tooling boundary capture -- [x] LaunchAgent and XPC service inventory -- [x] XPC ownership and entitlement correlation capture -- [x] Call-history storage schema inventory without row data -- [x] Call-history schema/index capture without row data -- [x] Call-history relationship/index/trigger boundary capture without row data -- [x] Public iPhoneOS 27.0 SDK header/interface inventory for CallKit and LiveCommunicationKit -- [x] Private `.tbd` notification and type-family inventory -- [x] Read-only Objective-C runtime metadata capture for call-history, TelephonyUtilities, and CallKit surfaces -- [x] Read-only Objective-C runtime metadata capture for CallsXPC, CallsPersistence, and PhoneAppIntents surfaces -- [x] Focused hook, XPC, host/vendor, call-history, and conversation runtime inventory -- [x] Bounded app-open log observation -- [x] First-pass notification delivery classification from launchd and SDK symbol evidence -- [x] Bounded app-open notification observer baseline without payload values -- [ ] Generated Swift/Objective-C interfaces from dyld cache or SDK metadata -- [ ] OS comparison against another macOS build +## Topic Index -## Boundary Map +- [Surfaces](surfaces.md): supported call APIs, URL schemes, manifests, and the public/private boundary. +- [Storage](storage.md): call-history schema, relationships, lifecycle metadata, and privacy limits. +- [Types](types.md): supported and private type families. +- [Symbols](symbols.md): SDK and live symbol evidence. +- [Agents](agents.md): apps, agents, daemons, plugins, and service ownership. +- [Runtime](runtime.md): Objective-C metadata and dyld-cache observations. +- [Hooks](hooks.md): intent, listener, query, callback, and interception surfaces. +- [Notifications](notifications.md): candidate names, delivery mechanisms, and observer evidence. +- [XPC ownership](xpc-ownership.md): launchd services, entitlements, clients, and authority boundaries. +- [Experiments](experiments.md): completed, blocked, and proposed research steps. -### Supported Public Surfaces +## Cross-Target Context -- `tel:` and FaceTime-related URL schemes for user-visible call initiation. -- CallKit for public call directory, VoIP call UI, and call-related extension surfaces. -- LiveCommunicationKit for public communication experiences where applicable. -- App Intents for app-owned actions, not general private call control. - -## Supported API Notes - -Verified from iPhoneOS and macOS 27.0 SDK headers/interfaces. - -### CallKit - -Local SDK headers expose the public call integration model through: - -- actions: `CXStartCallAction`, `CXAnswerCallAction`, `CXEndCallAction`, `CXSetHeldCallAction`, `CXSetMutedCallAction`, `CXSetGroupCallAction`, `CXPlayDTMFCallAction`, and `CXSetTranslatingCallAction` -- state/model objects: `CXCall`, `CXCallUpdate`, `CXHandle`, and `CXTransaction` -- orchestration: `CXProvider`, `CXProviderConfiguration`, `CXCallController`, and `CXCallObserver` -- call-directory extension support: `CXCallDirectoryProvider`, `CXCallDirectoryExtensionContext`, and `CXCallDirectoryManager` - -Inference: public CallKit supports app-owned calling services and call-directory behavior, but it is not a general interface to Phone’s private call history, voicemail store, or `callservicesd` control surface. - -### LiveCommunicationKit - -The Swift interface exposes: - -- `ConversationManager.Configuration` with ringtone, icon, conversation-group limits, recents inclusion, video support, supported handle types, and audio translation support -- `Conversation` with observable state and local member -- `ConversationAction` plus concrete `StartConversationAction`, `PauseConversationAction`, and `MergeConversationAction` -- `TelephonyConversationManager.sharedInstance`, `cellularServices`, and `startCellularConversation` -- `ConversationHistoryManager.sharedInstance` with recent-conversation queries and mark-read operations -- `ConversationHistoryDidUpdate` as a notification-center async message - -Inference: LiveCommunicationKit is the public route for modern conversation experiences and, where supported, default-dialer/cellular conversation integration. It does not expose the private Phone App Intents or TelephonyUtilities storage/control surfaces directly. - -### Private Local Surfaces - -- `Phone.app` and FaceTime-derived private app stack. -- `TelephonyUtilities`, `CallsXPC`, `CallsPersistence`, `CallHistory`, `CallHistoryToolKit`, `CallsUtilities`, `CallIntelligence`, and related call-service frameworks. -- `callservicesdaemon`, call history controllers, voicemail daemon, CommCenter, IDS, FaceTime message store, and Siri phone intents. -- Private call-history storage and platform entitlements. - -These are research surfaces only. They can explain how Phone works locally, but they are not supported integration contracts. - -## App Manifest Notes - -Verified from `Phone.app/Contents/Info.plist`: - -- Bundle identifier is `com.apple.mobilephone`. -- Executable is `Phone`. -- URL schemes include `tel`, `telephony`, `facetime-audio`, `tel-phoneapp`, `phoneapp`, and `vmshow`. -- `NSUserActivityTypes` includes `com.apple.facetime.handoff`. -- `NSDockTilePlugIn` is `PhoneDockTile.docktileplugin`. -- `UIApplicationSceneManifest` declares multi-scene support. -- `UIDeviceFamily` is `6`. - -Verified with `sdef /System/Applications/Phone.app`: - -- Phone does not expose a scripting dictionary on this machine. `sdef` returned error `-192`. - -## Entitlement Notes - -Verified from `codesign -d --entitlements :- /System/Applications/Phone.app`. - -Notable areas: - -- app identity: bundle identifier is `com.apple.mobilephone`, while `application-identifier` and previous identifiers include `0000000000.com.apple.FaceTime` -- call history: `com.apple.private.CallHistory.read-write`, `com.apple.CallHistory.sync.allow`, `com.apple.callhistory.pluginhelper` -- TelephonyUtilities: broad `com.apple.telephonyutilities.callservicesd` privileges, including access/modify calls, background calls, call providers, call capabilities, record calls, screen calls, translate calls, smart holding, media priorities, and participant reactions -- CommCenter: fine-grained access for cellular plan, phone, identity, SMS, data usage, and SPI -- FaceTime/IDS: FaceTime no-prompt, FaceTime message store, IDS messaging/registration, IMAV/IMCore access, and FaceTime live photo service -- storage: `com.apple.private.security.storage.CallHistory`, home-relative read/write for `/Library/CallHistoryDB/`, speed dial preferences, PeoplePicker preferences, and Contacts metadata -- URL privileges: default-handler and sensitive URL privileges for telephony, FaceTime, mobilephone, voicemail, and `sms-private` -- TCC/privacy: microphone, camera, calendar, reminders, contacts, photos, address book, and network privileges -- agent/service edges: mach lookup exceptions for `callservicesdaemon`, `CallHistoryPluginHelper`, `CallHistorySyncHelper`, `voicemail.vmd`, CommCenter, FaceTime message store, group activities, IDS, contacts, suggestions, and communication trust services - -Inference: macOS `Phone.app` is a FaceTime/call-services platform app with telephone, FaceTime audio, voicemail, call history, contacts, and call-control privileges layered through private daemons and frameworks. It is not a scriptable analogue of Messages. - -## Storage - -Verified call-history storage locations: - -- `~/Library/Application Support/CallHistoryDB/CallHistory.storedata` -- `~/Library/Application Support/CallHistoryDB/CallHistory.storedata-shm` -- `~/Library/Application Support/CallHistoryDB/CallHistory.storedata-wal` -- `~/Library/Application Support/CallHistoryDB/com.apple.callhistory.databaseInfo.plist` -- `~/Library/Application Support/CallHistoryTransactions/transactions.log` - -`com.apple.callhistory.databaseInfo.plist` reports `DatabaseVersionPerm` as `43`. - -Verified table inventory from `CallHistory.storedata` without reading row data: - -- `ZCALLDBPROPERTIES` -- `ZCALLRECORD` -- `ZEMERGENCYMEDIAITEM` -- `ZHANDLE` -- `Z_2REMOTEPARTICIPANTHANDLES` -- `Z_METADATA` -- `Z_MODELCACHE` -- `Z_PRIMARYKEY` - -High-signal schema notes: - -- `ZCALLRECORD` is the main call record table. It includes answered/originated/read state, call type/category, disconnect cause, FaceTime data flag, message flag, junk/confidence fields, communication trust score, emergency/video flags, verification status, timestamps, duration, service provider, country code, location/name/address fields, unique identifiers, conversation ID, participant group identifiers, local participant UUIDs, originating device name, and originating UI type. -- `ZHANDLE` stores normalized and raw handle values plus type. -- `Z_2REMOTEPARTICIPANTHANDLES` joins remote participant calls to handles. -- `pragma_foreign_key_list` returned no SQLite-enforced foreign keys, and `sqlite_schema` returned no trigger definitions. Relationship meaning is therefore Core Data model convention plus table/index naming, not SQLite trigger/foreign-key lifecycle enforcement. -- `ZCALLDBPROPERTIES`, `Z_METADATA`, `Z_MODELCACHE`, and `Z_PRIMARYKEY` are Core Data or store bookkeeping tables. -- `ZEMERGENCYMEDIAITEM` tracks emergency media assets and upload state. - -No call rows, phone numbers, names, addresses, durations, timestamps, voicemail metadata, or transaction-log contents were captured in this documentation pass. - -## Framework And Agent Map - -Verified active framework/app inventory includes: - -- public: `CallKit`, `CoreTelephony`, `LiveCommunicationKit`, `TelephonyMessagingKit` -- call private: `CallHistory`, `CallHistoryToolKit`, `CallIntelligence`, `CallsPersistence`, `CallsUtilities`, `CallsXPC`, `IncomingCallFilter` -- telephony private: `TelephonyUtilities`, `IPTelephony`, `CorePhoneNumbers`, `PhoneNumbers`, `PhoneNumberResolver`, `TelephonyBlastDoorSupport` -- Phone/Siri private: `PhoneAppIntents`, `PhoneSnippetUI`, `SiriPhoneIntents`, `SiriPhoneCATs` -- FaceTime adjacent: `FaceTimeMacHelperCore`, `FaceTimeMessageStore`, `FaceTimeFeatureControl`, `FaceTimeDockSupport`, notification frameworks, and iOSSupport FaceTime/PhoneKit/Calls frameworks - -The active app binary links to iOSSupport private frameworks including: - -- `PhoneKit` -- `CallsAppUI` -- `CallsAppServices` -- `CallsDialer` -- `CallsSearch` -- `FaceTimeMac` -- `FaceTimeAuthentication` -- `FaceTimeSettingsUI` -- `ConversationKit` -- `CommunicationsUI` - -It also links to macOS private frameworks including: - -- `CallHistory` -- `FaceTimeMessageStore` -- `IDS` -- `TelephonyUtilities` -- `CommunicationTrust` - -## Runtime Metadata Notes - -Verified by the local `spelunk objc-runtime` helper loading: - -- `/System/Library/PrivateFrameworks/TelephonyUtilities.framework/TelephonyUtilities` -- `/System/Library/PrivateFrameworks/CallHistory.framework/CallHistory` -- `/System/Library/Frameworks/CallKit.framework/CallKit` -- `/System/Library/PrivateFrameworks/CallsXPC.framework/CallsXPC` -- `/System/Library/PrivateFrameworks/CallsPersistence.framework/CallsPersistence` -- `/System/Library/PrivateFrameworks/PhoneAppIntents.framework/PhoneAppIntents` - -The capture also attempted `/System/Library/PrivateFrameworks/CallHistoryDB.framework/CallHistoryDB`; dyld reported no active file or dyld-cache image for that install name on this machine. - -The `TU*`, `CH*`, `Call*`, `CX*`, and `Phone*` capture produced 439 Objective-C classes and 181 Objective-C protocols on macOS 26.5.2. This is runtime metadata, not a generated public/private interface; method and property names are observed selectors/properties and still need behavior confirmation. - -The `Calls*`, `CX*`, `CH*`, `Phone*`, and selected `TU*` capture produced 225 Objective-C classes and 97 Objective-C protocols. See `types.md` for the stable type-family inventory. - -High-signal observed class families: - -- call history model/storage: `CHManager`, `CHRecentCall`, `CHHandle`, `CHPersistentContainer`, `CHTransaction`, `CallDBManager`, `CallDBManagerClient`, `CallHistoryDBHandle` -- telephony/call services: `TUCall`, `TUCallCenter`, `TUCallProvider`, `TUCallServicesInterface`, `TUCallHistoryController`, `TUCallHistoryManager`, `TUConversation`, `TUConversationManager`, `TUConversationProvider` -- call features: `TUCallRecording*`, `TUCallTranslation*`, `TUCallScreenShareAttributes`, `TUCollaboration*`, `TUConversationReactionsController` -- public CallKit runtime: `CXCall`, `CXCallController`, `CXProvider`, `CXTransaction`, `CXCallDirectory*`, `CXVoicemail*` - -Observed selector/property examples: - -- `CHManager` exposes recent-call fetching, coalescing, counting, read-state changes, delete/reset/clear operations, database size, sync transactions, and call-timer methods. -- `CHRecentCall` exposes call status/type/category, answered/originated/read state, participant handles, junk/verification/trust fields, emergency media fields, duration/date, local participant IDs, and message/voicemail-adjacent flags. -- `CHHandle` exposes normalized value, raw value, handle type, pseudonym, and temporary-handle checks. -- `TU*` classes expose the call-services model layer around live calls, conversations, call providers, call history controllers, recording, translation, continuity, and collaboration. - -Inference: Phone's local architecture splits persisted recents (`CH*` and `CallDB*`) from live call/conversation services (`TU*`) and public integration (`CX*`). The runtime metadata supports the storage and service split; it does not prove third-party access to private call mutation or history APIs. - -See `runtime.md` for app-open log observations covering the FaceTime app controller, Calls recents controller, FaceTimeMac window, Spotlight indexing, and Continuity Capture touchpoints. - -## Hook And XPC Notes - -See `hooks.md` for the focused hook-surface inventory generated from Objective-C runtime metadata. - -High-signal private hook families include: - -- `TUCallCenterXPCServer`, with private selectors for dialing requests, current call updates, recording, translation, smart holding, call pulling, call screening, greetings, and receptionist replies -- `TUConversationManagerXPCServer`, with conversation-link, SharePlay, activity-session, collaboration, Messages group, screen sharing, and participant-control selectors -- `TUCallHistoryControllerXPCServer` and `TUCallHistoryManagerXPCServer`, with client registration, deleted-recents, recent-call reporting, and participant UUID update selectors -- `CHManager`, `CHCallInteractionManager`, `CallDBManager`, `CallHistoryDBHandle`, and related store/handle classes for persisted call-history mediation -- `CXProviderHostProtocol`, `CXCallControllerHostProtocol`, and `CXVoicemailControllerHostProtocol`, with private CallKit host/vendor selectors - -Inference: Phone's private hooks center on `callservicesd` XPC protocols, CallHistory manager layers, and CallKit host internals. They are better evidence for brokered Apple platform architecture than for direct local database mutation. - -## SDK Symbol Notes - -Verified from macOS 27.0 SDK `.tbd` files. - -`CallsXPC`: - -- targets include macOS and Mac Catalyst -- exports Swift symbols for typed XPC messages, interfaces, identities, result errors, payload decoding, client/host message groups, and one-to-one interface kinds - -`CallsPersistence`: - -- exports Swift symbols around data-store wrappers, syncable entities, persistent history changes, fetch/save/delete/update failures, and delegate notifications for added/updated/deleted syncables - -`PhoneAppIntents`: - -- exports App Intents entities and values including `PhonePerson`, `CallRecord`, `CallMessage`, `CallAVMode`, and `CallStatus` -- `CallRecord` exposes intent-facing fields such as id, date, type, duration, provider, audio/visual mode, and remote participants -- `CallStatus` includes cases such as active, ringing, sending, on hold, disconnecting, disconnected, and unknown - -Inference: the beta SDK exposes a structured App Intents layer for Phone call records/messages and a Swift XPC/persistence stack for private call-service internals. - -Demangled `PhoneAppIntents` families from the macOS 27.0 SDK include: - -- `PhonePerson`: transient App Entity/App Value wrapper around `IntentPerson` -- `CallAVMode`: AppEnum with `audio` and `video` -- `CallStatus`: AppEnum with `active`, `ringing`, `sending`, `onHold`, `disconnecting`, `disconnected`, and `unknown`; includes a conversion from `TUCallStatus` -- `CallRecord`: App Entity, Indexed Entity, Syncable Entity, and Assistant Entity with `id`, `date`, `type`, `duration`, `provider`, `audioVisualMode`, and `remoteParticipants` -- `CallRecordQuery`: async entity query by string identifiers -- `CallMessage`: App Entity, Indexed Entity, Syncable Entity, Assistant Entity, model-representable, displayable, transferable entity with `id`, `date`, `from`, `duration`, `isRead`, `messageFile`, `voicemailTranscript`, and optional `callRecord` -- `CallMessageQuery`: async entity query by UUIDs -- `CallProvider`, `CallDestination`, and `CallRecordType` supporting call-record representation - -Demangled `CallsXPC` families include: - -- `XPCMessage`, with associated reply/failure types and static message identifiers -- `XPCInterface`, with host messages, client messages, interface kind, and identity -- `XPCIdentity.machService` -- `XPCMessages` with typed payload decoder maps -- `XPCHostConnection`, `XPCHost`, and `XPCClient`, with async send, sync send, message handlers, cancellation handlers, and entitlement lookup on connection requests -- one-to-one and one-to-many interface kinds - -Demangled `CallsPersistence` families include: - -- `SyncableEntity` and `Syncable` -- `DataStoreWrapper` with async fetch/count/object-id operations plus insert, update, and delete -- `DataStoreWrapperDelegate` callbacks for added, updated, deleted syncables, reconnect, and refetch requirements -- `DataStoreWrapperError` cases for batch delete, synchronization, persistent history, update, deletion, save, fetch, invalid state, store load, and invalid entity name - -Demangled `TelephonyUtilities` families include: - -- `VoiceSpamReportTelephonyManagerProtocol` and `VoiceSpamReportTelephonyManager` -- `BadgeCounts` and `BadgeCountCategory` -- `MessageStoreBadgeCounts` -- `RecordingMetadata` and `RecordingMediaComposer` -- `CallContextCardsHolder` - -## Dyld Shared Cache Notes - -Verified with: - -```sh -dyld_info -exports -objc -all_dyld_cache -``` - -The active arm64e shared cache is split under `/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/`. - -Observed export/symbol hints: - -- `TelephonyUtilities.VoiceSpamReportManagerProtocol` -- `TelephonyUtilities.VoiceSpamReportManager` -- `TelephonyUtilities.BadgeCounts` -- `TelephonyUtilities.AnalyticsLogger` -- `INSearchCallHistoryIntent` -- `INSearchCallHistoryIntentResponse` -- `SAPhoneCallHistory` -- `SAPhoneCallSearchResult` -- `CKSQLiteContainerAttribution_PhoneFaceTimeCallHistory` -- `CKSQLiteContainerAttribution_PhoneFaceTimeMessageStore` -- `kGEOCallHistoryRecentsClearedNotification` - -Boundary: `dyld_info` reported that it cannot print live Objective-C metadata from dylibs in the dyld shared cache. A later class/protocol/selector pass needs a different extraction path or a controlled runtime helper. - -## Launchd And XPC - -Verified LaunchAgents: - -| Label | Program | High-signal services or triggers | -| --- | --- | --- | -| `com.apple.callhistoryd` | `CallHistory.framework/Support/callhistoryd` | Mach services `com.apple.callhistoryd.service` and `com.apple.conversation.history` | -| `com.apple.CallHistoryPluginHelper` | `CallHistory.framework/Support/CallHistoryPluginHelper` | Mach service `com.apple.CallHistoryPluginHelper`; notify trigger `com.apple.CallHistoryPluginHelper.launchnotification` | -| `com.apple.CallHistorySyncHelper` | `CallHistory.framework/Support/CallHistorySyncHelper` | Mach services `com.apple.CallHistorySyncHelper` and `.aps`; IDS launch notification | -| `com.apple.callintelligenced` | `CallIntelligence.framework/callintelligenced` | Mach service `com.apple.callintelligenced.service`; first-unlock trigger | -| `com.apple.facetimemessagestored` | `FaceTimeMessageStore.framework/facetimemessagestored` | APS and FaceTime message-store mach services | -| `com.apple.telephonyutilities.callservicesd` | `TelephonyUtilities.framework/callservicesd` | CallKit, FaceTime alloy, call history, call state, conversation, provider, notification, VoIP, and simulated-conversation mach services | - -Verified XPC and extension bundles: - -| Bundle identifier | Bundle type | Notes | -| --- | --- | --- | -| `com.apple.TelephonyUtilities.PhoneIntentHandler` | intents extension | supports `INAddCallParticipantIntent`, `INJoinCallIntent`, `INStartCallIntent`, `INSearchCallHistoryIntent`, and `INPlayVoicemailIntent` | -| `com.apple.TelephonyBlastDoorService` | XPC service | application service with ProbGuard and shared-cache reslide | -| `com.apple.FaceTime.FTConversationService` | XPC service | FaceTime conversation service | -| `com.apple.FTLivePhotoService` | XPC service | FaceTime live photo service | - -Inference: Phone’s user-facing app sits above a broad `callservicesd` broker plus CallHistory, FaceTime, IDS, voicemail, and intent-handler surfaces. The exposed Siri/Intent verbs are narrower than the app’s private TelephonyUtilities entitlement set. - -## Open Questions - -- Which dyld-cache classes back `PhoneKit`, `CallsAppServices`, `CallsDialer`, and `TelephonyUtilities` behavior? -- Which `callservicesdaemon` XPC interfaces correspond to the broad `com.apple.telephonyutilities.callservicesd` entitlement values? -- Which Phone App Intents are user-invocable, Siri-only, or private/system-only? -- Which URL schemes open visible UI only versus initiating privileged background actions for Apple-signed callers? -- How does `Phone.app` divide responsibilities with `FaceTime.app` on macOS? -- Which remaining unclassified TelephonyUtilities and CallHistory notification constants are distributed, Darwin, notification-center, or internal-only? - -## References - -- `docs/frameworks/messages-phone-status.md` -- `research/Phone/README.md` -- `docs/frameworks/Phone/surfaces.md` -- `docs/frameworks/Phone/agents.md` -- `docs/frameworks/Phone/xpc-ownership.md` -- `docs/frameworks/Phone/storage.md` -- `docs/frameworks/Phone/symbols.md` -- `docs/frameworks/Phone/notifications.md` -- `docs/frameworks/Phone/types.md` -- `docs/frameworks/Phone/hooks.md` -- `docs/frameworks/Phone/runtime.md` -- `docs/frameworks/Phone/experiments.md` -- Apple Developer Documentation: [CallKit framework](https://developer.apple.com/documentation/callkit) -- Apple Developer Documentation: [CoreTelephony framework](https://developer.apple.com/documentation/coretelephony) -- Apple Developer Documentation: [LiveCommunicationKit framework](https://developer.apple.com/documentation/livecommunicationkit) -- Apple Developer Documentation: [LiveCommunicationKit `TelephonyConversationManager`](https://developer.apple.com/documentation/livecommunicationkit/telephonyconversationmanager) -- Apple Developer Documentation: [App Intents framework](https://developer.apple.com/documentation/appintents) +Phone and Messages share several communication-service boundaries. Use the [combined status map](../messages-phone-status.md) when a finding crosses both targets. diff --git a/docs/frameworks/Phone/baseline.md b/docs/frameworks/Phone/baseline.md new file mode 100644 index 0000000..30a5b8a --- /dev/null +++ b/docs/frameworks/Phone/baseline.md @@ -0,0 +1,378 @@ +# Phone Baseline + +## Scope + +Research `Phone.app`, `com.apple.mobilephone`, call history, telephony/call services, Phone App Intents, FaceTime-adjacent call surfaces, URL schemes, private frameworks, daemons, XPC services, storage, hooks, and supported public call APIs on macOS. + +This is private, local-only reverse-engineering research. Do not treat private APIs, entitlements, call-history stores, TelephonyUtilities services, or SIP-disabled behavior as public-release, App Store, customer-facing, or redistributed surfaces unless that separate analysis is explicitly opened. + +## Environment + +| Field | Value | +| --- | --- | +| Active OS | macOS 26.5.2 | +| Active OS build | 25F84 | +| Xcode path | `/Applications/Xcode-beta.app/Contents/Developer` | +| SDK comparison | macOS 27.0 SDK | +| SDK path | `$(xcrun --show-sdk-path --sdk macosx)` | +| Primary app path | `/System/Applications/Phone.app` | +| Bundle identifier | `com.apple.mobilephone` | +| App version | `1.0` | +| App build | `1` | + +## Evidence Inventory + +- [x] Active app path +- [x] App bundle identifier and URL schemes +- [x] App extension, plugin, URL, AppleScript, and intent surface inventory +- [x] App entitlement snapshot +- [x] Confirm no AppleScript dictionary via `sdef` +- [x] Active and SDK framework constellation inventory +- [x] App binary linked-library inventory +- [x] SDK `.tbd` symbol skim for `CallsXPC`, `CallsPersistence`, and `PhoneAppIntents` +- [x] Filtered dyld shared cache export probe +- [x] Live dyld cache residency and interface-tooling boundary capture +- [x] LaunchAgent and XPC service inventory +- [x] XPC ownership and entitlement correlation capture +- [x] Call-history storage schema inventory without row data +- [x] Call-history schema/index capture without row data +- [x] Call-history relationship/index/trigger boundary capture without row data +- [x] Public iPhoneOS 27.0 SDK header/interface inventory for CallKit and LiveCommunicationKit +- [x] Private `.tbd` notification and type-family inventory +- [x] Read-only Objective-C runtime metadata capture for call-history, TelephonyUtilities, and CallKit surfaces +- [x] Read-only Objective-C runtime metadata capture for CallsXPC, CallsPersistence, and PhoneAppIntents surfaces +- [x] Focused hook, XPC, host/vendor, call-history, and conversation runtime inventory +- [x] Bounded app-open log observation +- [x] First-pass notification delivery classification from launchd and SDK symbol evidence +- [x] Bounded app-open notification observer baseline without payload values +- [ ] Generated Swift/Objective-C interfaces from dyld cache or SDK metadata +- [ ] OS comparison against another macOS build + +## Boundary Map + +### Supported Public Surfaces + +- `tel:` and FaceTime-related URL schemes for user-visible call initiation. +- CallKit for public call directory, VoIP call UI, and call-related extension surfaces. +- LiveCommunicationKit for public communication experiences where applicable. +- App Intents for app-owned actions, not general private call control. + +## Supported API Notes + +Verified from iPhoneOS and macOS 27.0 SDK headers/interfaces. + +### CallKit + +Local SDK headers expose the public call integration model through: + +- actions: `CXStartCallAction`, `CXAnswerCallAction`, `CXEndCallAction`, `CXSetHeldCallAction`, `CXSetMutedCallAction`, `CXSetGroupCallAction`, `CXPlayDTMFCallAction`, and `CXSetTranslatingCallAction` +- state/model objects: `CXCall`, `CXCallUpdate`, `CXHandle`, and `CXTransaction` +- orchestration: `CXProvider`, `CXProviderConfiguration`, `CXCallController`, and `CXCallObserver` +- call-directory extension support: `CXCallDirectoryProvider`, `CXCallDirectoryExtensionContext`, and `CXCallDirectoryManager` + +Inference: public CallKit supports app-owned calling services and call-directory behavior, but it is not a general interface to Phone’s private call history, voicemail store, or `callservicesd` control surface. + +### LiveCommunicationKit + +The Swift interface exposes: + +- `ConversationManager.Configuration` with ringtone, icon, conversation-group limits, recents inclusion, video support, supported handle types, and audio translation support +- `Conversation` with observable state and local member +- `ConversationAction` plus concrete `StartConversationAction`, `PauseConversationAction`, and `MergeConversationAction` +- `TelephonyConversationManager.sharedInstance`, `cellularServices`, and `startCellularConversation` +- `ConversationHistoryManager.sharedInstance` with recent-conversation queries and mark-read operations +- `ConversationHistoryDidUpdate` as a notification-center async message + +Inference: LiveCommunicationKit is the public route for modern conversation experiences and, where supported, default-dialer/cellular conversation integration. It does not expose the private Phone App Intents or TelephonyUtilities storage/control surfaces directly. + +### Private Local Surfaces + +- `Phone.app` and FaceTime-derived private app stack. +- `TelephonyUtilities`, `CallsXPC`, `CallsPersistence`, `CallHistory`, `CallHistoryToolKit`, `CallsUtilities`, `CallIntelligence`, and related call-service frameworks. +- `callservicesdaemon`, call history controllers, voicemail daemon, CommCenter, IDS, FaceTime message store, and Siri phone intents. +- Private call-history storage and platform entitlements. + +These are research surfaces only. They can explain how Phone works locally, but they are not supported integration contracts. + +## App Manifest Notes + +Verified from `Phone.app/Contents/Info.plist`: + +- Bundle identifier is `com.apple.mobilephone`. +- Executable is `Phone`. +- URL schemes include `tel`, `telephony`, `facetime-audio`, `tel-phoneapp`, `phoneapp`, and `vmshow`. +- `NSUserActivityTypes` includes `com.apple.facetime.handoff`. +- `NSDockTilePlugIn` is `PhoneDockTile.docktileplugin`. +- `UIApplicationSceneManifest` declares multi-scene support. +- `UIDeviceFamily` is `6`. + +Verified with `sdef /System/Applications/Phone.app`: + +- Phone does not expose a scripting dictionary on this machine. `sdef` returned error `-192`. + +## Entitlement Notes + +Verified from `codesign -d --entitlements :- /System/Applications/Phone.app`. + +Notable areas: + +- app identity: bundle identifier is `com.apple.mobilephone`, while `application-identifier` and previous identifiers include `0000000000.com.apple.FaceTime` +- call history: `com.apple.private.CallHistory.read-write`, `com.apple.CallHistory.sync.allow`, `com.apple.callhistory.pluginhelper` +- TelephonyUtilities: broad `com.apple.telephonyutilities.callservicesd` privileges, including access/modify calls, background calls, call providers, call capabilities, record calls, screen calls, translate calls, smart holding, media priorities, and participant reactions +- CommCenter: fine-grained access for cellular plan, phone, identity, SMS, data usage, and SPI +- FaceTime/IDS: FaceTime no-prompt, FaceTime message store, IDS messaging/registration, IMAV/IMCore access, and FaceTime live photo service +- storage: `com.apple.private.security.storage.CallHistory`, home-relative read/write for `/Library/CallHistoryDB/`, speed dial preferences, PeoplePicker preferences, and Contacts metadata +- URL privileges: default-handler and sensitive URL privileges for telephony, FaceTime, mobilephone, voicemail, and `sms-private` +- TCC/privacy: microphone, camera, calendar, reminders, contacts, photos, address book, and network privileges +- agent/service edges: mach lookup exceptions for `callservicesdaemon`, `CallHistoryPluginHelper`, `CallHistorySyncHelper`, `voicemail.vmd`, CommCenter, FaceTime message store, group activities, IDS, contacts, suggestions, and communication trust services + +Inference: macOS `Phone.app` is a FaceTime/call-services platform app with telephone, FaceTime audio, voicemail, call history, contacts, and call-control privileges layered through private daemons and frameworks. It is not a scriptable analogue of Messages. + +## Storage + +Verified call-history storage locations: + +- `~/Library/Application Support/CallHistoryDB/CallHistory.storedata` +- `~/Library/Application Support/CallHistoryDB/CallHistory.storedata-shm` +- `~/Library/Application Support/CallHistoryDB/CallHistory.storedata-wal` +- `~/Library/Application Support/CallHistoryDB/com.apple.callhistory.databaseInfo.plist` +- `~/Library/Application Support/CallHistoryTransactions/transactions.log` + +`com.apple.callhistory.databaseInfo.plist` reports `DatabaseVersionPerm` as `43`. + +Verified table inventory from `CallHistory.storedata` without reading row data: + +- `ZCALLDBPROPERTIES` +- `ZCALLRECORD` +- `ZEMERGENCYMEDIAITEM` +- `ZHANDLE` +- `Z_2REMOTEPARTICIPANTHANDLES` +- `Z_METADATA` +- `Z_MODELCACHE` +- `Z_PRIMARYKEY` + +High-signal schema notes: + +- `ZCALLRECORD` is the main call record table. It includes answered/originated/read state, call type/category, disconnect cause, FaceTime data flag, message flag, junk/confidence fields, communication trust score, emergency/video flags, verification status, timestamps, duration, service provider, country code, location/name/address fields, unique identifiers, conversation ID, participant group identifiers, local participant UUIDs, originating device name, and originating UI type. +- `ZHANDLE` stores normalized and raw handle values plus type. +- `Z_2REMOTEPARTICIPANTHANDLES` joins remote participant calls to handles. +- `pragma_foreign_key_list` returned no SQLite-enforced foreign keys, and `sqlite_schema` returned no trigger definitions. Relationship meaning is therefore Core Data model convention plus table/index naming, not SQLite trigger/foreign-key lifecycle enforcement. +- `ZCALLDBPROPERTIES`, `Z_METADATA`, `Z_MODELCACHE`, and `Z_PRIMARYKEY` are Core Data or store bookkeeping tables. +- `ZEMERGENCYMEDIAITEM` tracks emergency media assets and upload state. + +No call rows, phone numbers, names, addresses, durations, timestamps, voicemail metadata, or transaction-log contents were captured in this documentation pass. + +## Framework And Agent Map + +Verified active framework/app inventory includes: + +- public: `CallKit`, `CoreTelephony`, `LiveCommunicationKit`, `TelephonyMessagingKit` +- call private: `CallHistory`, `CallHistoryToolKit`, `CallIntelligence`, `CallsPersistence`, `CallsUtilities`, `CallsXPC`, `IncomingCallFilter` +- telephony private: `TelephonyUtilities`, `IPTelephony`, `CorePhoneNumbers`, `PhoneNumbers`, `PhoneNumberResolver`, `TelephonyBlastDoorSupport` +- Phone/Siri private: `PhoneAppIntents`, `PhoneSnippetUI`, `SiriPhoneIntents`, `SiriPhoneCATs` +- FaceTime adjacent: `FaceTimeMacHelperCore`, `FaceTimeMessageStore`, `FaceTimeFeatureControl`, `FaceTimeDockSupport`, notification frameworks, and iOSSupport FaceTime/PhoneKit/Calls frameworks + +The active app binary links to iOSSupport private frameworks including: + +- `PhoneKit` +- `CallsAppUI` +- `CallsAppServices` +- `CallsDialer` +- `CallsSearch` +- `FaceTimeMac` +- `FaceTimeAuthentication` +- `FaceTimeSettingsUI` +- `ConversationKit` +- `CommunicationsUI` + +It also links to macOS private frameworks including: + +- `CallHistory` +- `FaceTimeMessageStore` +- `IDS` +- `TelephonyUtilities` +- `CommunicationTrust` + +## Runtime Metadata Notes + +Verified by the local `spelunk objc-runtime` helper loading: + +- `/System/Library/PrivateFrameworks/TelephonyUtilities.framework/TelephonyUtilities` +- `/System/Library/PrivateFrameworks/CallHistory.framework/CallHistory` +- `/System/Library/Frameworks/CallKit.framework/CallKit` +- `/System/Library/PrivateFrameworks/CallsXPC.framework/CallsXPC` +- `/System/Library/PrivateFrameworks/CallsPersistence.framework/CallsPersistence` +- `/System/Library/PrivateFrameworks/PhoneAppIntents.framework/PhoneAppIntents` + +The capture also attempted `/System/Library/PrivateFrameworks/CallHistoryDB.framework/CallHistoryDB`; dyld reported no active file or dyld-cache image for that install name on this machine. + +The `TU*`, `CH*`, `Call*`, `CX*`, and `Phone*` capture produced 439 Objective-C classes and 181 Objective-C protocols on macOS 26.5.2. This is runtime metadata, not a generated public/private interface; method and property names are observed selectors/properties and still need behavior confirmation. + +The `Calls*`, `CX*`, `CH*`, `Phone*`, and selected `TU*` capture produced 225 Objective-C classes and 97 Objective-C protocols. See `types.md` for the stable type-family inventory. + +High-signal observed class families: + +- call history model/storage: `CHManager`, `CHRecentCall`, `CHHandle`, `CHPersistentContainer`, `CHTransaction`, `CallDBManager`, `CallDBManagerClient`, `CallHistoryDBHandle` +- telephony/call services: `TUCall`, `TUCallCenter`, `TUCallProvider`, `TUCallServicesInterface`, `TUCallHistoryController`, `TUCallHistoryManager`, `TUConversation`, `TUConversationManager`, `TUConversationProvider` +- call features: `TUCallRecording*`, `TUCallTranslation*`, `TUCallScreenShareAttributes`, `TUCollaboration*`, `TUConversationReactionsController` +- public CallKit runtime: `CXCall`, `CXCallController`, `CXProvider`, `CXTransaction`, `CXCallDirectory*`, `CXVoicemail*` + +Observed selector/property examples: + +- `CHManager` exposes recent-call fetching, coalescing, counting, read-state changes, delete/reset/clear operations, database size, sync transactions, and call-timer methods. +- `CHRecentCall` exposes call status/type/category, answered/originated/read state, participant handles, junk/verification/trust fields, emergency media fields, duration/date, local participant IDs, and message/voicemail-adjacent flags. +- `CHHandle` exposes normalized value, raw value, handle type, pseudonym, and temporary-handle checks. +- `TU*` classes expose the call-services model layer around live calls, conversations, call providers, call history controllers, recording, translation, continuity, and collaboration. + +Inference: Phone's local architecture splits persisted recents (`CH*` and `CallDB*`) from live call/conversation services (`TU*`) and public integration (`CX*`). The runtime metadata supports the storage and service split; it does not prove third-party access to private call mutation or history APIs. + +See `runtime.md` for app-open log observations covering the FaceTime app controller, Calls recents controller, FaceTimeMac window, Spotlight indexing, and Continuity Capture touchpoints. + +## Hook And XPC Notes + +See `hooks.md` for the focused hook-surface inventory generated from Objective-C runtime metadata. + +High-signal private hook families include: + +- `TUCallCenterXPCServer`, with private selectors for dialing requests, current call updates, recording, translation, smart holding, call pulling, call screening, greetings, and receptionist replies +- `TUConversationManagerXPCServer`, with conversation-link, SharePlay, activity-session, collaboration, Messages group, screen sharing, and participant-control selectors +- `TUCallHistoryControllerXPCServer` and `TUCallHistoryManagerXPCServer`, with client registration, deleted-recents, recent-call reporting, and participant UUID update selectors +- `CHManager`, `CHCallInteractionManager`, `CallDBManager`, `CallHistoryDBHandle`, and related store/handle classes for persisted call-history mediation +- `CXProviderHostProtocol`, `CXCallControllerHostProtocol`, and `CXVoicemailControllerHostProtocol`, with private CallKit host/vendor selectors + +Inference: Phone's private hooks center on `callservicesd` XPC protocols, CallHistory manager layers, and CallKit host internals. They are better evidence for brokered Apple platform architecture than for direct local database mutation. + +## SDK Symbol Notes + +Verified from macOS 27.0 SDK `.tbd` files. + +`CallsXPC`: + +- targets include macOS and Mac Catalyst +- exports Swift symbols for typed XPC messages, interfaces, identities, result errors, payload decoding, client/host message groups, and one-to-one interface kinds + +`CallsPersistence`: + +- exports Swift symbols around data-store wrappers, syncable entities, persistent history changes, fetch/save/delete/update failures, and delegate notifications for added/updated/deleted syncables + +`PhoneAppIntents`: + +- exports App Intents entities and values including `PhonePerson`, `CallRecord`, `CallMessage`, `CallAVMode`, and `CallStatus` +- `CallRecord` exposes intent-facing fields such as id, date, type, duration, provider, audio/visual mode, and remote participants +- `CallStatus` includes cases such as active, ringing, sending, on hold, disconnecting, disconnected, and unknown + +Inference: the beta SDK exposes a structured App Intents layer for Phone call records/messages and a Swift XPC/persistence stack for private call-service internals. + +Demangled `PhoneAppIntents` families from the macOS 27.0 SDK include: + +- `PhonePerson`: transient App Entity/App Value wrapper around `IntentPerson` +- `CallAVMode`: AppEnum with `audio` and `video` +- `CallStatus`: AppEnum with `active`, `ringing`, `sending`, `onHold`, `disconnecting`, `disconnected`, and `unknown`; includes a conversion from `TUCallStatus` +- `CallRecord`: App Entity, Indexed Entity, Syncable Entity, and Assistant Entity with `id`, `date`, `type`, `duration`, `provider`, `audioVisualMode`, and `remoteParticipants` +- `CallRecordQuery`: async entity query by string identifiers +- `CallMessage`: App Entity, Indexed Entity, Syncable Entity, Assistant Entity, model-representable, displayable, transferable entity with `id`, `date`, `from`, `duration`, `isRead`, `messageFile`, `voicemailTranscript`, and optional `callRecord` +- `CallMessageQuery`: async entity query by UUIDs +- `CallProvider`, `CallDestination`, and `CallRecordType` supporting call-record representation + +Demangled `CallsXPC` families include: + +- `XPCMessage`, with associated reply/failure types and static message identifiers +- `XPCInterface`, with host messages, client messages, interface kind, and identity +- `XPCIdentity.machService` +- `XPCMessages` with typed payload decoder maps +- `XPCHostConnection`, `XPCHost`, and `XPCClient`, with async send, sync send, message handlers, cancellation handlers, and entitlement lookup on connection requests +- one-to-one and one-to-many interface kinds + +Demangled `CallsPersistence` families include: + +- `SyncableEntity` and `Syncable` +- `DataStoreWrapper` with async fetch/count/object-id operations plus insert, update, and delete +- `DataStoreWrapperDelegate` callbacks for added, updated, deleted syncables, reconnect, and refetch requirements +- `DataStoreWrapperError` cases for batch delete, synchronization, persistent history, update, deletion, save, fetch, invalid state, store load, and invalid entity name + +Demangled `TelephonyUtilities` families include: + +- `VoiceSpamReportTelephonyManagerProtocol` and `VoiceSpamReportTelephonyManager` +- `BadgeCounts` and `BadgeCountCategory` +- `MessageStoreBadgeCounts` +- `RecordingMetadata` and `RecordingMediaComposer` +- `CallContextCardsHolder` + +## Dyld Shared Cache Notes + +Verified with: + +```sh +dyld_info -exports -objc -all_dyld_cache +``` + +The active arm64e shared cache is split under `/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/`. + +Observed export/symbol hints: + +- `TelephonyUtilities.VoiceSpamReportManagerProtocol` +- `TelephonyUtilities.VoiceSpamReportManager` +- `TelephonyUtilities.BadgeCounts` +- `TelephonyUtilities.AnalyticsLogger` +- `INSearchCallHistoryIntent` +- `INSearchCallHistoryIntentResponse` +- `SAPhoneCallHistory` +- `SAPhoneCallSearchResult` +- `CKSQLiteContainerAttribution_PhoneFaceTimeCallHistory` +- `CKSQLiteContainerAttribution_PhoneFaceTimeMessageStore` +- `kGEOCallHistoryRecentsClearedNotification` + +Boundary: `dyld_info` reported that it cannot print live Objective-C metadata from dylibs in the dyld shared cache. A later class/protocol/selector pass needs a different extraction path or a controlled runtime helper. + +## Launchd And XPC + +Verified LaunchAgents: + +| Label | Program | High-signal services or triggers | +| --- | --- | --- | +| `com.apple.callhistoryd` | `CallHistory.framework/Support/callhistoryd` | Mach services `com.apple.callhistoryd.service` and `com.apple.conversation.history` | +| `com.apple.CallHistoryPluginHelper` | `CallHistory.framework/Support/CallHistoryPluginHelper` | Mach service `com.apple.CallHistoryPluginHelper`; notify trigger `com.apple.CallHistoryPluginHelper.launchnotification` | +| `com.apple.CallHistorySyncHelper` | `CallHistory.framework/Support/CallHistorySyncHelper` | Mach services `com.apple.CallHistorySyncHelper` and `.aps`; IDS launch notification | +| `com.apple.callintelligenced` | `CallIntelligence.framework/callintelligenced` | Mach service `com.apple.callintelligenced.service`; first-unlock trigger | +| `com.apple.facetimemessagestored` | `FaceTimeMessageStore.framework/facetimemessagestored` | APS and FaceTime message-store mach services | +| `com.apple.telephonyutilities.callservicesd` | `TelephonyUtilities.framework/callservicesd` | CallKit, FaceTime alloy, call history, call state, conversation, provider, notification, VoIP, and simulated-conversation mach services | + +Verified XPC and extension bundles: + +| Bundle identifier | Bundle type | Notes | +| --- | --- | --- | +| `com.apple.TelephonyUtilities.PhoneIntentHandler` | intents extension | supports `INAddCallParticipantIntent`, `INJoinCallIntent`, `INStartCallIntent`, `INSearchCallHistoryIntent`, and `INPlayVoicemailIntent` | +| `com.apple.TelephonyBlastDoorService` | XPC service | application service with ProbGuard and shared-cache reslide | +| `com.apple.FaceTime.FTConversationService` | XPC service | FaceTime conversation service | +| `com.apple.FTLivePhotoService` | XPC service | FaceTime live photo service | + +Inference: Phone’s user-facing app sits above a broad `callservicesd` broker plus CallHistory, FaceTime, IDS, voicemail, and intent-handler surfaces. The exposed Siri/Intent verbs are narrower than the app’s private TelephonyUtilities entitlement set. + +## Open Questions + +- Which dyld-cache classes back `PhoneKit`, `CallsAppServices`, `CallsDialer`, and `TelephonyUtilities` behavior? +- Which `callservicesdaemon` XPC interfaces correspond to the broad `com.apple.telephonyutilities.callservicesd` entitlement values? +- Which Phone App Intents are user-invocable, Siri-only, or private/system-only? +- Which URL schemes open visible UI only versus initiating privileged background actions for Apple-signed callers? +- How does `Phone.app` divide responsibilities with `FaceTime.app` on macOS? +- Which remaining unclassified TelephonyUtilities and CallHistory notification constants are distributed, Darwin, notification-center, or internal-only? + +## References + +- `docs/frameworks/messages-phone-status.md` +- `research/Phone/README.md` +- `docs/frameworks/Phone/surfaces.md` +- `docs/frameworks/Phone/agents.md` +- `docs/frameworks/Phone/xpc-ownership.md` +- `docs/frameworks/Phone/storage.md` +- `docs/frameworks/Phone/symbols.md` +- `docs/frameworks/Phone/notifications.md` +- `docs/frameworks/Phone/types.md` +- `docs/frameworks/Phone/hooks.md` +- `docs/frameworks/Phone/runtime.md` +- `docs/frameworks/Phone/experiments.md` +- Apple Developer Documentation: [CallKit framework](https://developer.apple.com/documentation/callkit) +- Apple Developer Documentation: [CoreTelephony framework](https://developer.apple.com/documentation/coretelephony) +- Apple Developer Documentation: [LiveCommunicationKit framework](https://developer.apple.com/documentation/livecommunicationkit) +- Apple Developer Documentation: [LiveCommunicationKit `TelephonyConversationManager`](https://developer.apple.com/documentation/livecommunicationkit/telephonyconversationmanager) +- Apple Developer Documentation: [App Intents framework](https://developer.apple.com/documentation/appintents)