Can a Developer ID profile carry the HomeKit entitlement?

[tobydoescode]

Part of #13

Question

Distribution is decided: Developer ID, notarised, direct download. That decision rests on an unverified assumption.

com.apple.developer.homekit is a restricted entitlement. Whether Apple issues it on a Developer ID provisioning profile — for distribution outside the Mac App Store — is unknown. If it does not, Developer ID distribution is impossible and the only paths left are local Xcode builds (with an expiring development profile) or the Mac App Store.

Establish against primary sources (Apple developer documentation, entitlement reference, Developer Account capability lists, forum posts only as corroboration):

1. Can a Mac Catalyst app signed for Developer ID distribution carry com.apple.developer.homekit? Is HomeKit listed among the capabilities available to Developer ID profiles?
2. Does the resulting app require an embedded provisioning profile at runtime, and if so what is that profile's validity period? Developer ID profiles are commonly longer-lived than development profiles — confirm the actual figure.
3. What happens when the embedded profile expires on an already-installed, already-notarised app? Does HomeKit stop initialising, or does the app keep working?
4. Does notarisation impose anything extra on restricted entitlements, or on Catalyst apps specifically?
5. Does NSHomeKitUsageDescription plus App Sandbox interact with any of this?
6. If Developer ID cannot carry it: what are the viable paths, and what does each cost in expiry/re-signing terms?

Answer should record

A direct verdict on question 1 with a citation, the profile validity period, expiry behaviour, and the fallback ranking if the answer is no.

[tobydoescode]

Verdict: No. A Developer ID profile cannot carry com.apple.developer.homekit.

Confidence high — four independent primary sources agree, two stating it directly rather than by inference. The map's standing constraint "Distribution: Developer ID, notarised, direct download" is unreachable for a HomeKit app and needs replacing.

There is also no way to apply for an exception: HomeKit is not a managed capability with an approval path.

1. Can it? No — HomeKit is Development / Ad Hoc / App Store only

a. Supported capabilities (macOS) — columns are ADP | Developer ID | Apple Developer. Extracted from raw DOM:

Capability	ADP	Developer ID	Apple Developer
iCloud: CloudKit	YES	YES	—
Push notifications	YES	YES	—
Network extensions	YES	YES	—
HomeKit	YES	—	—

The Developer ID column is populated for most rows, so blank is a deliberate signal. Apple DTS designates this exact page as the authority for this exact question (thread 761458, Aug 2024): "the first thing I'd check is that your restricted entitlements are compatible with Developer ID distribution. There's a table in Developer Account Help that lists most of them." TN3125 agrees: "Some entitlements are not supported by Developer ID profiles. For the details, see Supported capabilities (macOS)."

b. Xcode's own cached portal capability database — DVTPortalCachedPortalCapabilities.json in DVTPortal.framework (Xcode 26.4). The HOMEKIT record:

"distributionTypes": [ "AD_HOC", "DEVELOPMENT", "STORE" ],
"canRequestFromPortal": false,
"distributionApprovalRequired": false

DEVELOPER_ID is absent — and the absence is meaningful: 71 of the 196 capabilities in the file do carry it (ICLOUD, PUSH_NOTIFICATIONS, NETWORK_EXTENSIONS, MAPS, and notably ENABLED_FOR_MAC — the Catalyst checkbox itself). canRequestFromPortal: false means there is no form to file.

Validated as a predictor against three cases Apple has already confirmed: SHARED_WITH_YOU, APPLE_ID_AUTH (Sign in with Apple) and USER_ASSIGNED_DEVICE_NAME all have the identical shape and all produce the documented Catalyst Developer ID export error.

c. The entitlement's own documented availability excludes macOS and Catalyst: iOS, iPadOS, tvOS, visionOS, watchOS. The framework lists Mac Catalyst 14.0+ (API_AVAILABLE(..., macCatalyst(14.0)) API_UNAVAILABLE(macos) in the local SDK). API available, authorisation-outside-the-App-Store not.

d. The predicted error, observed in the wild (thread 651207, Jun 2020): "HomeKit capabilities are not available for Mac Catalyst Developer ID provisioning profiles. Disable these features and try again." Filed as FB7779724 — and six years later the capability record still lacks DEVELOPER_ID. Settled behaviour, not a bug. The string isn't in Xcode locally, so it's enforced server-side at profile issuance — you never reach a compiler or the notary.

Catalyst is not the problem — HomeKit is. Quinn/DTS: "it's perfectly valid to distribute a Mac Catalyst app outside of the Mac App Store using Developer ID" (699085). Every other surface (HTTP, EventKit, MCP, web UI) is Developer-ID-distributable fine.

No route around it: self-signing fails because a restricted entitlement without profile authorisation fails signature validation at launch (and "Mac Catalyst apps always use the data protection keychain, and you can't do that without a provisioning profile"); a HomeKit helper process still needs its own Developer-ID-compatible profile; MATTER_ALLOW_SETUP_PAYLOAD is Developer-ID-eligible but only covers pairing payloads, not the home database.

2. Embedded profile + validity: 18 years

Required, and for Catalyst unconditionally — the data protection keychain forces a profile regardless of HomeKit. Location MyApp.app/Contents/embedded.provisionprofile.

Developer ID support: "Developer ID provisioning profiles generated after February 22, 2017, are valid for 18 years from the creation date, regardless of the expiration date of your Developer ID certificate." Restated in Developer Account Help and announced by Apple Staff in 2017. Corroborated: Quinn's Mar 2022 profile expires 15 Mar 2040 — exactly 18 years. Certificate is separately 5 years. Development profiles: "typically not more than a year" (TN3125 — Apple states no exact figure).

3. On expiry: the app stops launching — neither option the ticket proposed

Developer ID support: "Gatekeeper … will evaluate the validity of your Developer ID provisioning profile at every app launch. … However, if your Developer ID provisioning profile expires, the app will no longer launch." It is a launch gate, not per-entitlement degradation — HomeKit does not quietly stop initialising.

Unresolved contradiction, recorded honestly: Quinn in Apr 2020 said the opposite — "the system is meant to ignore them… A Developer ID-sign product should not expire" — then reverted in Mar 2022 to "it'll stop working when that profile expires." No Apple source after Mar 2022 settles it. Academic given the 18-year window.

Certificate expiry is benign: signed-and-timestamped apps keep installing and running; only revocation kills installed apps. Note the common claim that notarisation acts as the timestamp is wrong — it's the secure timestamp (--timestamp, timestamp.apple.com), which notarisation requires but isn't synonymous with.

4-5. Notarisation and sandbox: nothing extra

The notary checks signature, Developer ID cert, hardened runtime, secure timestamp, get-task-allow, and entitlement XML wellformedness. Provisioning profiles are not mentioned on either notarisation page — there is no documented check that entitlements are profile-authorised. So notarising proves nothing here (false negative). No Catalyst-specific notarisation rules exist at all. No App Sandbox entitlement exists for HomeKit (verified: zero hits in the App Sandbox topic list); NSHomeKitUsageDescription is a crash-avoidance purpose string with no documented entitlement interaction. Minor map correction: Catalyst App Sandbox is automatic by default and mandatory for the Mac App Store — not documented as mandatory for Developer ID.

6. Fallback ranking

Ranked for this project — a headless daemon on one Mac the maintainer owns, which makes development signing far cheaper than usual.

1. Local development signing — HomeKit works (PoC already proves it). Cost: re-sign ~annually, one xcodebuild run, no Apple round-trip. Needs the Mac in the team device list. Gives up notarisation and distribution to others; keeps launchd, local HTTP server, bearer token, no App Review.
2. Mac App Store — the only path with zero recurring re-signing. Cost: App Review on an app that hands an agent destructive control of the home over a local HTTP server; loses /usr/local/bin, keys.json moves into the container, launchd via SMAppService.
3. TestFlight, internal testers only — HomeKit works, no Beta App Review. Cost: 90-day build expiry, so a mandatory quarterly upload-and-reinstall plus a cloud dependency. Worse than Update dependency typescript to v6 #1 for an unattended daemon.

Not viable: Developer ID + HomeKit; Developer ID app with a HomeKit helper; ad-hoc/self-signed with the entitlement forced in; applying to Apple; native macOS target (API_UNAVAILABLE(macos)); Matter entitlement as a substitute.

Recommendation: #1 for the destination, #2 held in reserve if the app ever needs to reach another person's Mac. Replace the distribution constraint and drop "notarised" from the destination — it is unreachable together with HomeKit.

Two cheap tests that would make this empirical rather than documentary

1. Try to mint a Developer ID profile for the derived maccatalyst.* App ID with HomeKit enabled, then security cms -D -i embedded.provisionprofile | plutil -p - | grep -i homekit. Expect HomeKit absent, or the App ID missing from the picker.
2. xcodebuild -exportArchive with method: developer-id on a HomeKit-entitled archive. Expect the quoted error.

Recommended before rewriting the map's distribution constraint. A DTS code-level request (team FRB6K6JADV) is the only route to an officially citable statement, but is belt-and-braces given four concurring sources.

---

Full write-up: docs/research/developer-id-homekit-entitlement.md on branch research/developer-id-homekit-entitlement (commit 81a8a8f, not merged, no PR).

⚠️ Methodology warning for anyone re-deriving this: Apple's doc and Account Help pages are JS-rendered, and an LLM-summarising fetch of the macOS capability table fabricated a checkmark for HomeKit under Developer ID — the exact opposite of the truth. Every table claim here came from raw HTML DOM parsing, independently reproduced by a second agent in a real browser. Use https://developer.apple.com/tutorials/data/documentation/<path>.json for doc pages.