iOS Photos full access: establishing and verifying PHAccessLevelReadWrite¶
setAppPermissions with photos on a simulator runs simctl privacy <udid> grant photos <bundle>
(src/utils/ios-cmdline-tools/IosPermissionsBackend.ts), which stores a kTCCServicePhotos row.
Nothing shows that this grant gives the app effective full access: on iOS 26.5 / Xcode 26.6 the app’s own
PHPhotoLibrary.authorizationStatus(for: .readWrite) stays notDetermined, and .addOnly becomes
authorized only after photos-add (#12317). No one has verified any simulator/runtime combination, and
nothing here has device verification. Physical-device limits stay the same.
Grant outcomes¶
Implemented in src/features/action/IosSimulatorPermissions.ts (classifyIosSimulatorPermission,
verifyPhotosGrant). PhotosAuthorizationVerifier is an injectable seam for target-app
instrumentation; the production default is unobservable.
| Observation | Result |
|---|---|
| Default (dispatched, unobservable), or verifier/TCC-readback throws | success: true, applied: true, verified: false, warning, code: "PHOTOS_FULL_ACCESS_UNVERIFIED"; counts as changed; warnings aggregate in warnings; exceptions logged at warn; a readback exception returns this before consulting the verifier |
authorized read/write |
Verified success, no code or warning |
Positive limited, denied, notDetermined, addOnly |
Typed failure PHOTOS_FULL_ACCESS_NOT_ESTABLISHED, applied: true, verified: false, accessLevel: "readWrite", actionable error |
- The unverified warning tells the user to launch the app and check
PHPhotoLibrary authorizationStatusForAccessLevel:ReadWrite. Add-only is insufficient;photos-addis a separate dispatch success. - For
all, a confirmed Photos failure keeps the successfulalldispatch (applied: true) and adds a separate failedphotosresult. Non-Photos services are not marked failed, only Photos incrementsfailedCount, and the top-level error is the first failed result’s. - The facade maps each result to its own operation with a permission-specific
stepIdand exposes its code. getAppPermissionsclassifies a stored Photos grant asunknown,verified: false,evidence: "storedTccGrant"(#12316, #12368); stored TCC grants are evidence only.
What the host can observe¶
PHPhotoLibrary.authorizationStatus(for:)(iOS 14+) reports the calling process’s own identity. Raw values:notDetermined0,restricted1,denied2,authorized3,limited4.- Querying never prompts; only
requestAuthorization(for:handler:)does. A request needsNSPhotoLibraryUsageDescription(read/write) /NSPhotoLibraryAddUsageDescription(add-only); the status query needs neither. - The CtrlProxy runner resets authorization with
XCUIApplication.resetAuthorizationStatus(for:)(ios/control-proxy/Sources/CtrlProxy/GesturePerformer.swift), using.photosfor bothphotosandphotos-add:XCUIProtectedResourcehas only.photos, so it cannot distinguish the levels. XCUITest has no public API to read another app’s authorization status, and the runner’s own status describes the runner process, not the target. - Stored TCC rows are host-readable (
SimulatorTccSqliteClient.tsmapsphotostokTCCServicePhotos,photos-addtokTCCServicePhotosAdd), but a storedauth_value=2row is not the effective PhotoKit status, so TCC is not a verification channel.
Playground probe¶
ios/Playground/Sources/PhotosAuthorizationProbe.swift writes Documents/photos-authorization.json
at launch: readWrite and addOnly, each { rawValue, name }, plus observedAt. It never calls
requestAuthorization. The Playground Info.plist has both usage-description keys. The host reads the
file with simctl get_app_container <udid> <bundle> data (the channel src/server/appFileService.ts
uses; same pattern as ios/UserDefaultsProbe/Probe.swift and
scripts/ios/userdefaults-no-sdk-smoke.sh). It reports the probe app’s state, so it can establish
what a grant sequence does per simulator/runtime/Xcode but cannot make setAppPermissions report
verified: true for another app.
Implied add-only readback¶
Readback infers photos-add from a full kTCCServicePhotos grant (auth_value 2) only on simulator
runtime major >= 27 (#12462, #12486). Runtime version comes from device.iosVersion or
device.osVersion; with an unknown runtime, readback reports the stored PhotosAdd row. Fixtures are in
test/fixtures/ios-tcc-photos/: the 27.0 capture shows add-only authorized even with a stale
PhotosAdd row; the iOS 26.5 set shows PhotoKit addOnly notDetermined after reset+grant photos and
denied after revoke+grant photos.