| ... | ... | @@ -0,0 +1,866 @@ |
| 1 | # Export iCloud data to Snow Globe |
| 2 | |
| 3 | Export **9 GB of Voice Memos first** inside the dedicated macOS VM, then |
| 4 | trial optimized native Photos exports of **about 1.7 TB** to Snow Globe. |
| 5 | These are the only requested categories. Keep original media, edited versions, and |
| 6 | metadata in ordinary Windows-readable files, organized by year with mtimes |
| 7 | set from recording dates. The remote friend supplies Apple sign-in and |
| 8 | two-factor approval; the iPhone never needs to hold the whole library or |
| 9 | connect to Clover's Mac by cable. |
| 10 | |
| 11 | The storage split is confirmed by the friend's iCloud storage screenshot. |
| 12 | Apple sign-in, two-factor approval, and encrypted-data authorization are complete |
| 13 | in the dedicated VM. Advanced Data Protection remains on. Unrelated app sync |
| 14 | is disabled in this guest. The source iPhone reports **348 All Recordings, |
| 15 | 1 favorite, and 2 Recently Deleted**. |
| 16 | |
| 17 | The Mac catalog contains 358 rows. On macOS 26, the native playable predicate |
| 18 | `flags != nil AND flags & 6 != 0` recognizes **348 active recordings**, matching |
| 19 | the phone, plus two deleted recordings. The native favorite count is one. |
| 20 | Two active recordings are shorter than 0.1 seconds; duration filtering would |
| 21 | exclude them and incorrectly include two stale catalog entries. Use the native |
| 22 | predicate when selecting recordings, and preserve all 358 catalog rows. |
| 23 | |
| 24 | The macOS 15 cache exposed 161 audio files. A fresh macOS 26 import retrieved |
| 25 | 350 files totaling 9,612,921,523 bytes: 161 `.m4a` and 189 `.qta`, including the |
| 26 | two deleted recordings. All 348 active recordings now have audio references. |
| 27 | The complete host and native checks recovered **310 active recordings** passing full |
| 28 | stereo decoding and catalog-duration checks. The remaining 38 older `.m4a` |
| 29 | recordings comprise five empty files, 14 headers without a readable container, |
| 30 | and 19 decodable files shorter than their catalog duration. Both independent |
| 31 | native downloads retrieved the same legacy bytes. Keep these originals and |
| 32 | their metadata; do not claim a complete export or delete cloud data. |
| 33 | |
| 34 | The `.qta` files contain stereo AAC alongside newer audio tracks. Native macOS |
| 35 | 26 validation checked every audio track without playback. Portable stereo |
| 36 | `.m4a` copies can reuse the original AAC packets without re-encoding; retain |
| 37 | the byte-identical `.qta` originals to preserve spatial/layer and other metadata. |
| 38 | |
| 39 | Three pilot files totaling 107,836,545 bytes passed source/host/NAS SHA-256, |
| 40 | full decoding, duration reconciliation, and exact recording-time mtime checks. |
| 41 | The macOS 15 local-file pass found 123 files passing full decoding and catalog |
| 42 | and decoded duration checks; 19 decode but are shorter than their catalog |
| 43 | duration, and 14 nonempty files contain headers without a `moov` atom. The |
| 44 | five zero-byte files are excluded from the portable set. Failed and incomplete |
| 45 | files remain in the native archive, with private per-record validation results. |
| 46 | |
| 47 | The public delivery root `/srv/clover/Share/iCloud Export - 2026-11-04` |
| 48 | contains only `Voice Memos/<year>/...`: **310 validated recordings**, delivered |
| 49 | as 310 Windows `.m4a` files and 187 original `.qta` files, totaling |
| 50 | 12,163,467,515 bytes. The first 123 recordings remain included. Pilot, |
| 51 | Available, native databases, manifests, and helper folders are absent. |
| 52 | The original `.qta` files preserve every track and embedded field. Their stereo |
| 53 | copies preserve identical AAC packets without re-encoding. Both audio tracks |
| 54 | of every active `.qta` passed native macOS 26 decoding: 187 recordings, |
| 55 | 374 tracks. Source/host/NAS hashes and recording-time mtimes match. |
| 56 | |
| 57 | Native files and metadata are outside the share at |
| 58 | `/srv/clover/.icloud-export-private/2026-11-04`, behind a mode-0700 parent: |
| 59 | |
| 60 | - `Native initial snapshot`: 232 source/support files totaling 1,746,210,872 |
| 61 | bytes, including a consistent SQLite backup with all 358 rows. |
| 62 | - `Native macOS 26 snapshot`: 351 files totaling 9,615,002,291 bytes, |
| 63 | including all 350 media files and a consistent 358-row SQLite backup. |
| 64 | - `Portable metadata`: complete recording index, original titles, source and |
| 65 | portable inventories, native validation results, and the recovery index. |
| 66 | |
| 67 | Both native databases pass `quick_check` on Mac and NAS. The existing |
| 68 | password-protected read-only share URL is unchanged. Live HTTP tests verify |
| 69 | an initial file, a new original and stereo copy, recording-time headers, |
| 70 | range requests, and denial of writes and parent access. TAR downloads preserve |
| 71 | whole-second recording mtimes and the `Voice Memos/<year>` layout. The friend |
| 72 | has **not yet tested Windows playback or Date modified**. |
| 73 | |
| 74 | A separate protected recovery share at |
| 75 | `/srv/clover/Share/iCloud Export Recovery - 2026-11-04` contains instructions |
| 76 | identifying the 38 exceptions and an `Uploads` inbox. Its URL is in |
| 77 | `private/recovery-share.json`; it uses the same password as the delivery share. |
| 78 | Instruction names are generated mechanically for the friend and never printed. |
| 79 | Uploads and authenticated downloads pass; deletion and parent access are denied. |
| 80 | The friend checks the originals on the iPhone, exports available recordings as |
| 81 | Rendered audio, and names each upload using the checklist's `recovery-NNN` |
| 82 | identifier. The private recovery index maps that identifier to the original |
| 83 | recording date, catalog duration, and title for later verification and replacement. |
| 84 | The recovery share now also has `Partial recordings/<year>/...`: 19 untouched |
| 85 | short originals and 28 reconstructed candidates covering the other 14 nonempty |
| 86 | exceptions. Both 44.1 kHz and 48 kHz headers are retained for those 14 because |
| 87 | the source header is missing. All 47 files pass decoding, NAS hash, mtime, and |
| 88 | live HTTP checks; every reconstructed encoded packet occurs in its untouched |
| 89 | source. These 33 logical partial recordings do not count toward the 310 complete |
| 90 | recordings. Candidate audio rate still needs comparison with the original source. |
| 91 | Never publish incomplete files as successfully recovered recordings. |
| 92 | |
| 93 | The audio sync worker was restarted in this guest after the native snapshot; |
| 94 | counts and bytes remained unchanged. The normal share manager rolled back because its success-text check does not |
| 95 | recognize Copyparty’s current reload response. A read-only password-protected |
| 96 | link was instead created through Copyparty’s native HTTP API for the dated |
| 97 | export root. Unauthenticated reads return 401; authenticated media hashes and |
| 98 | HTTP mtimes match; range requests work; writes and parent access return 403. |
| 99 | The URL and password-file path are in `private/export-share.json`. Evidence remains in the VM's restricted |
| 100 | `evidence/*-nas-validation.json`; private per-file manifests are not operator |
| 101 | readable output. |
| 102 | |
| 103 | ## Privacy boundary |
| 104 | |
| 105 | Expose only basic metadata and aggregate integrity results: counts, byte |
| 106 | sizes, dates, durations, and opaque identifiers. Do not display or listen to |
| 107 | media, inspect transcripts or thumbnails, or reveal filenames, recording |
| 108 | titles, GPS coordinates, or other location information in chat or operator |
| 109 | logs. Keep media apps closed during authentication and exclude profile |
| 110 | images and media windows from authentication captures. |
| 111 | |
| 112 | Automated workers may copy, hash, and validate files without exposing their |
| 113 | contents. Preserve original bytes and all metadata, including location data, |
| 114 | inside the friend's restricted archive; withholding metadata from the operator |
| 115 | must not strip it from the export. Names and metadata may be handled |
| 116 | mechanically inside private workers and manifests without returning their |
| 117 | values. The friend performs any visual or listening review on Windows. |
| 118 | These constraints take precedence over manual sample inspection below. |
| 119 | |
| 120 | ## Agreed order |
| 121 | |
| 122 | 1. Create a fresh macOS VM on this Mac, prove its console and guest control, |
| 123 | then sign into the friend's Apple Account and enable Voice Memos only. |
| 124 | A separate host macOS account remains an alternative if the VM pilot fails. |
| 125 | 2. Prove a small memo export, then download and reconcile the full 9 GB, |
| 126 | preserve native sources, and share the dated portable files from Snow Globe. |
| 127 | Check the result on the friend's Windows PC. |
| 128 | 3. Trial native Photos exports using the VM's existing Apple session. |
| 129 | Check originals, edits, companions, counts, dates, and cache space before |
| 130 | the full run. The web downloader requires separate authentication and |
| 131 | remains an alternative when the friend is available. |
| 132 | |
| 133 | ## Capacity and cleanup |
| 134 | |
| 135 | Read-only measurements on 4 November 2026, in decimal GB and TB: |
| 136 | |
| 137 | | Storage | Used | Available | Allocation | |
| 138 | | --- | ---: | ---: | --- | |
| 139 | | Project | 567.5 GB | Shared below | APFS volume on the 2 TB WD Blue SN5000 | |
| 140 | | Documents | 1183.3 GB | Shared below | Same APFS container as Project | |
| 141 | | Project and Documents container | About 1751 GB | **249.1 GB total** | 2000.2 GB capacity; no volume quotas or reserves | |
| 142 | | Mac startup container | About 895 GB | 99.2 GB | Separate 994.7 GB APFS container | |
| 143 | | Snow Globe personal storage | — | About 7.79 TB | ZFS availability for `/srv/clover` | |
| 144 | |
| 145 | Project and Documents already share free space. Shrinking one APFS volume |
| 146 | does not give the other more space; moving or deleting verified data frees |
| 147 | their common pool. Neither volume currently has APFS snapshots. These are |
| 148 | volumes on a physical disk, not sparse disk images that can be compacted. |
| 149 | |
| 150 | The **9 GB memo run needs no disk cleanup**. For the VM route, reserve about |
| 151 | 100 GB of the Documents container's available 249 GB for a 64 GB guest disk, |
| 152 | the restore-image download, and transfer/scratch space. This is a planning |
| 153 | budget from before installation. After the macOS 26 upgrade, backups, and |
| 154 | full memo export, the shared container still has about **134.3 GB free**; |
| 155 | no personal files were removed. A host-account fallback |
| 156 | would instead use the startup disk's available 99 GB for the memo store. |
| 157 | |
| 158 | The current Photos route keeps an optimized local library and sends exported |
| 159 | files to Snow Globe. It reuses the existing Apple login and supplies a native |
| 160 | catalog for reconciliation. Original downloads temporarily consume guest and |
| 161 | host disk space; the trial must establish a workable batch size and cache |
| 162 | reclamation behavior. |
| 163 | |
| 164 | For a full Download Originals library, budget **about 1.85 TB free** in the shared |
| 165 | Project/Documents container: 1.7 TB of photos plus an initial 150 GB allowance |
| 166 | for databases, caches, and temporary files. That means freeing **about 1.60 TB |
| 167 | more** against the pre-VM measurement above. A retained memo VM consumes space |
| 168 | in this same pool, so add its actual allocation and remeasure before cleanup. |
| 169 | The iCloud size is rounded and the allowance is a planning target. Export |
| 170 | directly to Snow Globe to avoid a second full local media set. |
| 171 | |
| 172 | Any eventual cleanup must follow the recovery requirements in |
| 173 | [AGENTS.md](../AGENTS.md). NAS space must then cover both relocated Clover |
| 174 | data and the friend's export, including edited versions. |
| 175 | |
| 176 | ## Dedicated VM route |
| 177 | |
| 178 | Apple supports iCloud in macOS VMs created using a macOS 15 or later restore |
| 179 | image on a macOS 15 or later Apple silicon host. Upgrading a VM originally |
| 180 | created with an older OS does not add this support. VM identities are tied |
| 181 | to the host's Secure Enclave; moving a VM or running another clone can require |
| 182 | reauthentication. |
| 183 | [Apple's iCloud virtualization requirements](https://developer.apple.com/documentation/virtualization/using-icloud-with-macos-virtual-machines). |
| 184 | |
| 185 | This host runs macOS 15.7.5 and has 256 GiB RAM. Its existing Tart guest is |
| 186 | the running `gui-agent`, exposed as `m3-devbox`. The installed |
| 187 | Tart 2.41.1 supports fresh IPSW installation and a specified guest disk size. |
| 188 | Apple's Sequoia license, section 2B(iii), permits two additional virtual macOS |
| 189 | instances for the listed purposes, including personal noncommercial use. |
| 190 | [macOS Sequoia license](https://www.apple.com/legal/sla/docs/macOSSequoia.pdf). |
| 191 | |
| 192 | The pilot has four vCPUs and 8 GiB RAM. Its initially 64 GB sparse disk has |
| 193 | been enlarged to 128 GB for the macOS 26 compatibility test. It was created |
| 194 | from Apple's macOS 15.6.1 restore image, build 24G90, with verified SHA-256 |
| 195 | `3d87686b691ac765eb6a6b3082b2334e2af9710096a00432dd519af89ff2ea78`. |
| 196 | The Apple CDN URL and installation evidence are in its private `evidence` |
| 197 | directory. The initial macOS 15.8.2 guest recognized only 161 of 348 as playable. |
| 198 | The guest has now booted macOS 26.7.2 for the compatibility test, matching the |
| 199 | phone’s iOS 26.6.1 generation. |
| 200 | |
| 201 | Reuse the installed signed Tart binary and the control approach documented |
| 202 | in [the devbox runbook](mac-agent-vm.md), with a separate VM state directory |
| 203 | under `/Volumes/Documents/VM/macOS Code Sandbox/icloud-export`. Its existing |
| 204 | ancestor ACL protects this tree on Documents, where ownership is disabled. |
| 205 | Keep its disk, credentials, and transfer directory there. Keep the devbox |
| 206 | guest and its active work separate. A fresh install avoids copying devbox |
| 207 | accounts, credentials, and workspace mounts, and establishes the required |
| 208 | installation provenance; cloning is not categorically incompatible with iCloud. |
| 209 | |
| 210 | [Tart's fresh-install procedure](https://tart.run/quick-start/) begins with |
| 211 | `tart create --from-ipsw IMAGE --disk-size 64 icloud-export`, followed by guest |
| 212 | Setup Assistant. Use the isolated state directory for every command. Keep |
| 213 | only a dedicated transfer folder available to the guest, then copy verified |
| 214 | portable output to the NAS from the host. |
| 215 | |
| 216 | Console access, input, capture, guest storage, and the transfer path have been |
| 217 | proved before Apple sign-in. The existing dashboard bridge selects `m3-devbox` |
| 218 | specifically; it does not automatically control another guest. A dedicated |
| 219 | guest console/control connection can run while Clover stays in the existing |
| 220 | host login. This avoids creating or switching to another host account. |
| 221 | The friend still provides Apple authentication and two-factor approval. |
| 222 | Supported iCloud sign-in is a prerequisite; the pilot must also establish |
| 223 | actual Voice Memos sync, complete audio downloads, and a verified export. |
| 224 | |
| 225 | ### Resume this pilot |
| 226 | |
| 227 | The guest has been upgraded to macOS 26.7.2, matching the phone's iOS 26.6.1 |
| 228 | generation. It was cleanly shut down first. APFS clones of the stopped |
| 229 | `disk.img`, `nvram.bin`, and `config.json` remain in `private/pre-tahoe`; all |
| 230 | 64 GB of the old disk passed byte comparison. Never run this backup |
| 231 | concurrently or alter its VM identity. |
| 232 | |
| 233 | The guest disk is now 128 GB. Its Recovery partition was copied to the new |
| 234 | end without changing partition identifiers; all 5,368,668,160 Recovery bytes |
| 235 | passed hash verification, and both GPT copies pass CRC checks. Apple's |
| 236 | `diskutil apfs resizeContainer` then expanded the guest system container, |
| 237 | leaving about 97.8 GB free. No host partitions or devbox disks changed. A temporary Virtualization VNC |
| 238 | server was closed before input because it listens on all host interfaces; |
| 239 | normal runs remain headless with no host VNC listener. |
| 240 | `evidence/pre-tahoe-backup.json` and `recovery-relocation.json` record these |
| 241 | checks. Apple Software Update downloaded the 26.7.2 installer, and the in-place guest |
| 242 | upgrade completed and the guest has booted macOS 26.7.2. The macOS 26 desktop is open. A one-boot automatic login bypassed unreliable |
| 243 | Screen Sharing password entry, then its root cleanup job removed the setting, |
| 244 | `/etc/kcpassword`, and its own plist. Automatic login is disabled; the guest now reports FileVault enabled. The local |
| 245 | password, keychain, and Apple Account are unchanged. The one-boot setup helper |
| 246 | was removed to prevent replay; evidence is `one-boot-login-validation.json`. |
| 247 | `sysadminctl`'s prompted form returned error 22, so the temporary credential was |
| 248 | written to its normal root-only file over stdin; no secret appeared in argv or |
| 249 | logs. Executable signatures verify; the installer intentionally |
| 250 | uses legacy resource omission rules rejected by a generic Gatekeeper app |
| 251 | assessment. No security policy was changed. `startosinstall` uses the guest |
| 252 | local volume-owner password over stdin, never command arguments. The completed login is verified by console UID 501, the login-done flag, and |
| 253 | Finder/Dock processes; a GUI launchd domain alone does not establish login. The |
| 254 | lock-state guard uses pinned guest SSH because the login-session Tart agent |
| 255 | is unavailable before console login. |
| 256 | |
| 257 | All machine-specific state is under |
| 258 | `/Volumes/Documents/VM/macOS Code Sandbox/icloud-export`. `state` is its |
| 259 | isolated Tart home; the VM name is `icloud-export`. A symlink in |
| 260 | `~/.tart/vms/icloud-export` names this same guest. The local guest account is |
| 261 | `admin`; its generated password and separate SSH key remain in `private`. |
| 262 | The friend's Apple credentials belong only in `private/apple-account.json`, |
| 263 | with fields `apple_account` and `password`. The guest does not |
| 264 | mount that directory. |
| 265 | |
| 266 | `private/run-vm.py` runs only this guest. Launch it detached through the |
| 267 | existing localhost SSH route so it survives the controlling shell. It mounts |
| 268 | `transfer/tooling` read-only and `transfer/output` read/write. The guest sees |
| 269 | these as `/Volumes/My Shared Files/tooling` and `output`. Host paths outside |
| 270 | these two directories are not shared with it. |
| 271 | |
| 272 | `private/vm-ui.py` takes JSON on stdin for guest screenshots and input. |
| 273 | It uses vncdotool 1.3.0's Apple Screen Sharing authentication over SSH, with |
| 274 | a guest-specific key and pinned host key. Its Unix viewer |
| 275 | socket stays inside `private`. The physical Mac can remain locked. The |
| 276 | temporary Tart installer VNC listener is stopped, its credentials are removed, |
| 277 | and normal pilot starts omit `--vnc-experimental`. The temporary legacy VNC |
| 278 | password was also disabled and removed; the console uses the local account. |
| 279 | |
| 280 | Native Screen Sharing maps `super` to Command. Its `clear` operation uses |
| 281 | Command–A then Backspace; individual character events are paced. A public |
| 282 | test containing upper/lowercase letters, underscore, hyphen, plus, and an |
| 283 | email address was reproduced exactly. The sign-in field and guest clipboard |
| 284 | were cleared after the check. Guest login and console reconnection passed |
| 285 | after the OS update and the final VM restart. Automatic login remains disabled. The native console |
| 286 | controller is now closed; the headless guest desktop remains active and SSH |
| 287 | metadata access remains available. No host VNC listener is enabled. |
| 288 | |
| 289 | For guest commands, use the installed Tart binary with |
| 290 | `TART_HOME="/Volumes/Documents/VM/macOS Code Sandbox/icloud-export/state"` |
| 291 | and `exec icloud-export COMMAND`. The guest agent runs only its command RPC; |
| 292 | clipboard integration is off. SSH offers a second command route and supplies |
| 293 | the private screen-sharing tunnel. Never point the existing devbox installer |
| 294 | or its lifecycle commands at this pilot. |
| 295 | |
| 296 | The synthetic transfer fixture was removed after passing its hash and mtime |
| 297 | checks. Pilot evidence is in `evidence/pilot-nas-validation.json`. |
| 298 | |
| 299 | The iPhone passcode file was deleted after successful authorization. Never |
| 300 | reset encrypted iCloud data. Read credentials only inside the input worker; |
| 301 | never print or display their files. Authentication captures use restricted |
| 302 | regions and mask inputs before writing images. Never capture a media window. |
| 303 | |
| 304 | `private/vm-ui.py --stream` maintains one guest console connection across JSON |
| 305 | lines. Do not infer the guest lock state from the VNC connection status. Verify |
| 306 | it through `ioreg`; automatic login remains disabled. Controller |
| 307 | capture defaults to false. A menubar-only crop can verify the active app |
| 308 | without exposing recording names. Start the controller PTY with `stty -icanon -echo`; macOS canonical input |
| 309 | truncates long JSON lines. Counted Up/Down steps are supported, and counted |
| 310 | Backspace requires the locked-guest guard. Explicit paced Shift combinations |
| 311 | handle the US keyboard layout without exposing credentials. |
| 312 | |
| 313 | Voice Memos' migrated local store was preserved intact at guest |
| 314 | `/Users/admin/iCloudExportRecovery/Recordings-before-refetch`. A fresh |
| 315 | `Recordings` store has imported all 358 catalog rows. Its first stable pass |
| 316 | retrieved 103 media paths, including 18 `.qta` recordings absent from the |
| 317 | macOS 15 store. This changes only the local cache, not iCloud records. |
| 318 | The fresh assets require native decoding/export for formats unsupported by the |
| 319 | host FFmpeg; a decode failure alone does not establish source corruption. |
| 320 | Launch GUI apps through the guest agent in the completed desktop session. |
| 321 | OSLaunchdErrorDomain 125 was observed before console login completed. |
| 322 | Keep all credential input on stdin. The optional post-upgrade assistant was |
| 323 | closed without approving extra cloud services. |
| 324 | |
| 325 | `private/memo-export.py` reports aggregate status without arguments; `recovered` |
| 326 | copies and validates stable files from the current native store. Selection uses |
| 327 | the native playable predicate, including sub-0.1-second recordings. Existing |
| 328 | validation is reused only for identical hashes, recording times, and catalog |
| 329 | durations. Initial `pilot` and `available` inventories are historical evidence. |
| 330 | `native-audio-check.py` validates every QTA audio track with the native decoder; |
| 331 | PCM scratch is discarded after checking frame counts and duration. |
| 332 | `build-portable.py` preserves original media and builds packet-identical stereo |
| 333 | copies. `publish-macOS26.py` has completed its sealed native snapshot publication; |
| 334 | do not replay it against the existing native destination. Future updates must |
| 335 | preserve the flat public layout and private recovery material. Report 310 of |
| 336 | 348 complete recordings until the remaining 38 reconcile. |
| 337 | |
| 338 | ### Photos without another Apple login |
| 339 | |
| 340 | The friend is unavailable for another verification code. The separate web-login |
| 341 | worker has stopped, its pending request was denied in the VM, and its unused |
| 342 | NAS password copy and cookies were removed. No additional code was requested. |
| 343 | Use Photos in the already signed-in VM with Optimize Mac Storage, exporting |
| 344 | requested originals and edits in batches through native Photos/PhotoKit or |
| 345 | OSXPhotos. |
| 346 | Photos is now enabled in that same Apple session and has begun importing its |
| 347 | catalog. Optimize Mac Storage is selected and independently verified through |
| 348 | its native settings control. Keep the library on the guest's local APFS disk |
| 349 | and send exported files to Snow Globe. Apple advises against putting a Photos |
| 350 | library on a network share. |
| 351 | |
| 352 | The catalog holds 38,142 assets: 37,804 visible (1,823,889,190,154 original |
| 353 | bytes; 4,544 videos, 1,348 edited, 363 Live Photos), 303 hidden burst members, |
| 354 | and 35 in Recently Deleted. No shared albums exist. OSXPhotos 0.78.0 runs in the |
| 355 | guest from `~/.local/bin` (installed with a checksum-verified uv 0.9.7). |
| 356 | |
| 357 | PhotoKit needs Photos access from a responsible app with a usage string; CLI |
| 358 | processes under SSH or Terminal are refused or time out before the prompt can be |
| 359 | answered. `transfer/tooling/PhotoExport.app` is an ad-hoc-signed launcher |
| 360 | (`net.paperclover.icloud-export.photos`) that spawns its arguments, and holds |
| 361 | full Photos access in the guest. Terminal also received access while this was |
| 362 | diagnosed. Prompts are `UserNotificationCenter` alerts; answer them with |
| 363 | `run_steps` by button name, never with screenshots. |
| 364 | |
| 365 | Guest `~/PhotoExport` holds the private inventory, 110 date-ordered UUID batches |
| 366 | (about 15 GB each; `b0000` is a 30-asset pilot), and per-batch logs, reports, |
| 367 | and export databases. `driver.py` (from `private/photos-driver.py`), started by |
| 368 | `open -n ~/Applications/PhotoExport.app --args /bin/sh ~/PhotoExport/run.command`, |
| 369 | exports each batch with `--download-missing --use-photokit`, year directories, |
| 370 | `{date}_{uuid}` names, XMP sidecars, and `--touch-file`, then repeats it once |
| 371 | with `--update`. It keeps at most one unshipped batch and pauses below 25 GB |
| 372 | free; `~/PhotoExport/STOP` halts it between batches. On the host, |
| 373 | `private/photos-ship.py` streams each finished batch to Snow Globe, verifying |
| 374 | every file's size, SHA-256, and mtime. Media goes to `Photos/<year>` in the |
| 375 | delivery share; sidecars, reports, and export databases go to the private |
| 376 | `Photos metadata/<batch>`. Only then is guest staging deleted. Logs: |
| 377 | `evidence/photos-ship.log` and guest `driver.log`. |
| 378 | |
| 379 | The pilot exported 223 files (30 assets and their burst members) with no |
| 380 | missing or failed items, and passed mtime, year-folder, and file-signature |
| 381 | checks before shipping. |
| 382 | |
| 383 | Downloaded originals stay in the Photos cache until space pressure. In this |
| 384 | guest the per-user `deleted` (CacheDelete) agent had a stale volume object |
| 385 | ("unable to validate volume"), so nothing was purgeable and Photos never evicted, |
| 386 | even at 3 GB free. Killing that agent, then quitting and reopening Photos, made |
| 387 | the cache purgeable; pressure at about 6 GB free then evicted 9.5 GB within |
| 388 | seconds. Before each batch below 40 GB free, the driver preallocates a temporary |
| 389 | balloon down to 6 GB, waits 30 s, and deletes it. If purges stop freeing space, |
| 390 | check `NSURLVolumeAvailableCapacityForImportantUsageKey` and the `deleted` log first. |
| 391 | |
| 392 | A full local download of the 1.7 TB is not a prerequisite for this optimized |
| 393 | route. Originals are temporarily downloaded by Photos as exports request them; |
| 394 | Photos manages eviction. Cache reclamation is asynchronous, so verify bounded |
| 395 | space use in a trial, monitor free space, and pause before exhausting the guest |
| 396 | or host disk. Do not use OSXPhotos `--cleanup` to evict cloud originals: it |
| 397 | removes files from the export destination. |
| 398 | [Apple Photos and iCloud](https://support.apple.com/en-euro/guide/photos/phtf5e48489c/mac) · |
| 399 | [OSXPhotos maintainer on optimized storage](https://github.com/RhetTbull/osxphotos/discussions/1926) · |
| 400 | [Apple library-storage requirements](https://support.apple.com/en-us/108345). |
| 401 | |
| 402 | The alternative web downloader remains installed privately on Snow Globe: |
| 403 | upstream `icloudpd` 1.33.0 at |
| 404 | `/srv/clover/.icloud-export-private/2026-11-04/tools/icloudpd-1.33.0`, pinned to |
| 405 | commit `3caeae584c3d8bc6fcc51a1c9f7e5413b1422fd3`. It requires its own Apple web |
| 406 | session. Keep its cookies and credentials private; leave ADP enabled. It is |
| 407 | not the current route while the friend cannot supply another code. |
| 408 | |
| 409 | ### Remaining memo recovery checks |
| 410 | |
| 411 | The cached CloudKit records use LZFSE/LZVN compression. After decompression, |
| 412 | all 38 exception assets' recorded sizes match the local files, including the |
| 413 | five empty files. Their latest cloud modification predates this export: |
| 414 | 24 February 2026. Each has one audio-future generation in the cached index. |
| 415 | No additional Voice Memos audio was found in its app/group stores. Native Core |
| 416 | Audio decoding of all 33 nonempty exceptions recovers 19 short streams but |
| 417 | none of the full catalog durations; the other 14 fail native decoding too. |
| 418 | Some short files contain additional `mdat`/`moof` fragments, retained for repair |
| 419 | experiments. The audio was never uploaded. The 38 cloud assets hold 1,221,488 bytes |
| 420 | for 9.7 catalog hours, and each record's own local duration is 0–22 seconds, |
| 421 | whereas healthy recordings match their catalog duration. No Mac-side or iCloud |
| 422 | copy can supply the rest; only the iPhone (or a local backup of it) can, if its |
| 423 | copy is complete. A normal app export has now been attempted for all 38: all 19 short files |
| 424 | remain short, 18 supply no audio, and one empty item cannot be copied through |
| 425 | the UI. Repair with a pinned build of `anthwlock/untrunc` produced decodable |
| 426 | fragments for all 14 header-only files (16.831 seconds across their longest |
| 427 | candidates), but no full catalog durations. The original 19 short files remain |
| 428 | better than their reconstructed variants and are retained untouched. |
| 429 | Evidence is `recovery-cloud-metadata-validation.json`, with private atom, |
| 430 | packet, and native-decoder inventories. Never display media, names, or locations. |
| 431 | |
| 432 | ## What each person does |
| 433 | |
| 434 | Once the export login is controllable, the agent can configure the export, |
| 435 | oversee sync and retries, read the authorized memo database, restore names |
| 436 | and dates, verify files, and manage the restricted NAS delivery. |
| 437 | |
| 438 | Guest installation and its local account can be prepared from Clover's |
| 439 | existing host session. The separate host-account alternative requires Clover |
| 440 | to authenticate account creation: the host shell runs as `clo` without |
| 441 | passwordless sudo. |
| 442 | |
| 443 | The friend keeps the subscription active, enters Apple credentials and any |
| 444 | encrypted-data authentication, approves two-factor requests on the iPhone, |
| 445 | checks source counts, and tests Windows playback. Remote sign-in needs both |
| 446 | credentials and two-factor approval; approving a notification is insufficient |
| 447 | on its own. |
| 448 | |
| 449 | Current Cua Driver checks pass for Accessibility, Screen Recording permission, |
| 450 | AX access, and the WindowServer connection in Clover's login. The locked host |
| 451 | desktop refused GUI control; the pilot's independent guest console works. |
| 452 | For the host-account alternative, first login and |
| 453 | the GUI controller's access must be established in that login, including any |
| 454 | per-user permissions. Keep the existing Knife session available in Clover's |
| 455 | account. A host account switch must not log it out. |
| 456 | These setup and authentication steps can be done through a trusted remote |
| 457 | connection while the Mac is powered on and reachable; they do not inherently |
| 458 | require a visit to the machine. |
| 459 | |
| 460 | Use the restricted credential file or a private remote-control session into |
| 461 | the export VM for password entry. Device-passcode entry and two-factor |
| 462 | approval may still require the friend. Credentials, recovery keys, and verification codes stay out of |
| 463 | chat, shell arguments, repository files, and export logs. The temporary Mac |
| 464 | becomes an authorized device with access to the account; the friend should |
| 465 | understand that before signing in. |
| 466 | |
| 467 | ## Before downloading |
| 468 | |
| 469 | 1. Confirm the friend's iOS version and whether Advanced Data Protection is |
| 470 | enabled. The requested storage split is 9 GB of memos and about 1.7 TB of |
| 471 | Photos; other account categories are outside the export. |
| 472 | 2. Record Photos' photo/video counts with filters cleared. Inventory Hidden, |
| 473 | personal and Shared Photo Libraries, Shared Albums, bursts, RAW pairs, |
| 474 | edited media, and anything wanted from Recently Deleted. Do the same for |
| 475 | Voice Memos, including custom folders and Recently Deleted. Do not restore |
| 476 | deleted items without the friend's choice. |
| 477 | 3. Confirm both Photos and Voice Memos are enabled in iCloud on the iPhone |
| 478 | and have finished uploading. Phone-only items cannot be fetched from |
| 479 | iCloud. Resolve upload errors on the source first. |
| 480 | 4. Agree how future photos and recordings will be protected after migration. |
| 481 | A one-time export does not upload tomorrow's recordings. |
| 482 | |
| 483 | ## Host account alternative |
| 484 | |
| 485 | Use a new standard user dedicated to this export, with its normal home under |
| 486 | `/Users` on the startup disk. The 9 GB memo store does not justify a custom |
| 487 | home directory or another APFS volume. Clover authenticates account creation |
| 488 | through the Mac's administrator prompt; do not put passwords in command |
| 489 | arguments. Test first login and the account's GUI control before sign-in. |
| 490 | |
| 491 | Sign into the friend's Apple Account in that user, leaving Clover's normal |
| 492 | account signed in separately. Review the iCloud app switches during setup and |
| 493 | enable Voice Memos only. Keep Photos and Drive sync off for this phase. Leave |
| 494 | Find My, Passwords and Keychain, Messages, and purchase-account sign-in out |
| 495 | of this setup. Decline merging unrelated local data. |
| 496 | |
| 497 | Only for the native Photos fallback, create the friend's Photos library in |
| 498 | a private folder on the existing Project/Documents APFS disk after freeing |
| 499 | space. Make it that user's System Photo Library, enable iCloud Photos, and |
| 500 | select **Download Originals to this Mac**. Keep the Mac powered, awake, and |
| 501 | connected during downloads. Do not put the live `.photoslibrary` on the NAS: |
| 502 | Apple requires appropriate local Mac-formatted storage and warns against |
| 503 | network storage for live libraries. |
| 504 | [Apple's library storage requirements](https://support.apple.com/en-us/108345). |
| 505 | |
| 506 | A cable import would require the iCloud originals to be downloaded onto the |
| 507 | iPhone first. It is therefore unsuitable for this 1.7 TB photo library; a cable |
| 508 | copy does not inherently mean all embedded camera metadata is lost. |
| 509 | [Apple's PC import requirements](https://support.apple.com/en-us/120267). |
| 510 | |
| 511 | Layered Voice Memos require at least macOS 15.2. The initial macOS 15 guest |
| 512 | proved insufficient for this catalog; the phone runs iOS 26.6.1, and a macOS 26 |
| 513 | compatibility test is underway. |
| 514 | [Apple's Voice Memos playback requirements](https://support.apple.com/en-euro/guide/voice-memos/vma2c8c0a040/mac). |
| 515 | |
| 516 | ## Prove a small export first |
| 517 | |
| 518 | For the memo pilot, test ordinary, renamed, trimmed, long, and layered |
| 519 | recordings where present. Include a recording close to New Year or a timezone |
| 520 | boundary. |
| 521 | |
| 522 | For the subsequent Photos trial, test an old and a new photo, duplicate |
| 523 | original filenames, an edited picture, a Live Photo, a video, a burst, a RAW |
| 524 | pair if present, a hidden item, and a date corrected in Photos. |
| 525 | |
| 526 | The friend opens the pilot on Windows and checks appearance, sound, edits, |
| 527 | duration, filenames, and dates. An original plus its edited rendition are two |
| 528 | intentional versions. A Live Photo's image and video must both survive. |
| 529 | Full-resolution originals and all companions must exist; thumbnails and a |
| 530 | matching item count are insufficient. |
| 531 | |
| 532 | ## Native Photos fallback |
| 533 | |
| 534 | Use [OSXPhotos](https://rhettbull.github.io/osxphotos/index.html) to export the |
| 535 | downloaded library. Its year and UUID templates give ordinary directories |
| 536 | without filename collisions. Keep original names and album membership in |
| 537 | metadata rather than duplicating media into every album. |
| 538 | [Template reference](https://rhettbull.github.io/osxphotos/template_help.html). |
| 539 | |
| 540 | Run the export as the operator with read access to the friend's downloaded |
| 541 | library and write access to the destination. Using Clover's operator account |
| 542 | for this phase keeps NAS credentials outside the temporary Apple login. |
| 543 | Grant access only to the agreed source tree; macOS privacy permissions may |
| 544 | also be required. Always pass the explicit library path. Do not let the tool |
| 545 | fall back to Clover's own Photos library. |
| 546 | |
| 547 | Example paths below are placeholders. Confirm the NAS mount and its backing |
| 548 | host before creating the destination. Keep export state on the Mac; only |
| 549 | validated portable media belongs in the public share. Keep catalog metadata |
| 550 | and native recovery files in restricted staging outside it. |
| 551 | |
| 552 | ```sh |
| 553 | uv tool install 'osxphotos==0.78.0' |
| 554 | |
| 555 | LIBRARY='/Volumes/Documents/iCloud Export/Photos Library.photoslibrary' |
| 556 | WORK="$HOME/Library/Application Support/iCloud Export" |
| 557 | mkdir -p "$WORK/photo-staging" |
| 558 | chmod 700 "$WORK" |
| 559 | |
| 560 | osxphotos info --library "$LIBRARY" --json > "$WORK/photos-info.json" |
| 561 | osxphotos query --library "$LIBRARY" --json > "$WORK/photos.json" |
| 562 | |
| 563 | osxphotos export "$WORK/photo-staging" \ |
| 564 | --library "$LIBRARY" \ |
| 565 | --directory '{created.year}' \ |
| 566 | --filename '{created.strftime,%Y-%m-%d_%H%M%S}_{uuid}' \ |
| 567 | --touch-file \ |
| 568 | --sidecar xmp \ |
| 569 | --keyword-template '{folder_album(>)}' \ |
| 570 | --exportdb "$WORK/photos-export.db" \ |
| 571 | --update \ |
| 572 | --report "$WORK/photos-export.csv" |
| 573 | ``` |
| 574 | |
| 575 | Capture dry-run and tool diagnostics privately; return only aggregate progress |
| 576 | and integrity results. Never display private paths or media metadata. Add |
| 577 | `--limit 30` for a pilot, then remove the limit for the full export. Retain the |
| 578 | export database and options for retries and the final update. Keep dated |
| 579 | copies of reports before subsequent runs replace them. Defaults export |
| 580 | originals, edited versions, Live Photo videos, burst members, and associated |
| 581 | RAW images; edited files receive an `_edited` suffix. `--touch-file` sets the |
| 582 | media mtime from the Photos date. Do not enable overwrite or cleanup options. |
| 583 | [Export command reference](https://rhettbull.github.io/osxphotos/cli). |
| 584 | |
| 585 | Wait for full hydration and inspect missing/error reports. For exceptions, |
| 586 | OSXPhotos has `--download-missing`, but its documentation says this does not |
| 587 | retrieve every burst member. Resolve every missing companion explicitly. |
| 588 | For network exports, a local export database avoids putting its SQLite writes |
| 589 | on SMB. XMP sidecars preserve catalog metadata without rewriting original |
| 590 | media bytes; the JSON inventory keeps the broader catalog information. Retain |
| 591 | these sidecars and inventories outside the public media-only share. |
| 592 | [Export and metadata tutorial](https://rhettbull.github.io/osxphotos/tutorial.html). |
| 593 | |
| 594 | Apple's built-in fallback is **File → Export → Export Unmodified Original** |
| 595 | with **Export IPTC as XMP**, plus a separate export of edited versions. A Live |
| 596 | Photo exports as an image and a video. This fallback still needs inventory |
| 597 | matching and timestamp correction for the proposed layout. |
| 598 | [Apple's export procedure](https://support.apple.com/en-gb/guide/photos/pht6e157c5f/mac). |
| 599 | |
| 600 | ## Export Voice Memos |
| 601 | |
| 602 | The database contains metadata; audio lives in separate files. Enable Voice |
| 603 | Memos sync in the temporary user, open the app, and reconcile its recordings |
| 604 | with the iPhone. A listed recording is not proof its audio is downloaded. |
| 605 | [Apple's sync procedure](https://support.apple.com/en-ie/guide/voice-memos/vma6cc4d0571/mac). |
| 606 | |
| 607 | The current common store is: |
| 608 | |
| 609 | ```text |
| 610 | ~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/ |
| 611 | CloudRecordings.db |
| 612 | CloudRecordings.db-wal when present |
| 613 | CloudRecordings.db-shm when present |
| 614 | media and supporting files |
| 615 | ``` |
| 616 | |
| 617 | Preserve a private copy of the entire native store, including editing and |
| 618 | supporting files. Use SQLite's backup API through a read-only source connection |
| 619 | to obtain a consistent database snapshot including committed WAL data. Copying |
| 620 | only the live `.db`, or opening it with `immutable=1`, can miss recent changes. |
| 621 | Quiesce app edits during the copy and reconcile again afterward. |
| 622 | [SQLite's backup API](https://www.sqlite.org/backup.html). |
| 623 | |
| 624 | Inspect the copied schema before implementing extraction. Published exporters |
| 625 | use `ZCLOUDRECORDING`, `ZUNIQUEID`, `ZPATH`, `ZDATE`, and `ZDURATION`; one |
| 626 | documents `ZEVICTIONDATE` for deleted state. These are reverse-engineered |
| 627 | details, so verify their meaning against this account's app views. Titles can |
| 628 | occupy different fields; preserve them mechanically in private metadata without |
| 629 | displaying them. Native `.m4a` and `.qta` files both occur. |
| 630 | [Exporter schema and SQLite handling](https://github.com/grapeot/voice-memos-skill/blob/master/docs/rfc.md). |
| 631 | |
| 632 | The extraction contract is: |
| 633 | |
| 634 | ```text |
| 635 | for each wanted logical recording in the database: |
| 636 | require a local, nonempty, decodable media file |
| 637 | reconcile duration, active/deleted state, and recording ID |
| 638 | preserve the original title privately without operator inspection |
| 639 | recording instant = ZDATE + 978307200 seconds since Unix epoch |
| 640 | copy native media without changing its bytes |
| 641 | export a rendered copy when edits/layers/effects need rendering |
| 642 | name portable output YYYY-MM-DD_HHMMSSZ_unique-id.ext |
| 643 | set mtime from the recording instant |
| 644 | record ID, full title, date, duration, folder, variant, and output path |
| 645 | ``` |
| 646 | |
| 647 | The epoch conversion applies only after confirming `ZDATE` uses Apple's 2001 |
| 648 | epoch in this store. Use UTC for memo filenames and year folders if historical |
| 649 | recording timezones are unavailable; preserve any known timezone separately. |
| 650 | Opaque UUID filenames avoid Windows-invalid characters and private titles or |
| 651 | locations in paths. Preserve full titles privately. Do not merge duplicate |
| 652 | titles or infer dates from download times. |
| 653 | |
| 654 | An ordinary native M4A is suitable when its playback matches the app. Compare |
| 655 | trimmed recordings too: raw file copying alone must not silently discard edits. |
| 656 | For special recordings, export both the native editable source and a rendered |
| 657 | M4A. Apple documents rendered sharing as mixing effects and layers into one |
| 658 | file. The remote friend can select recordings on their iPhone, choose **Share |
| 659 | → Options → Rendered**, save a manageable batch locally, and upload it through |
| 660 | a temporary folder-scoped HTTPS upload link. Export editable versions too when |
| 661 | the source is not already preserved on the Mac. No physical proximity is |
| 662 | needed; do not ask the phone to download the entire photo library. |
| 663 | [Apple's multiple-recording sharing options](https://support.apple.com/en-mt/guide/iphone/iph3d6dc359/ios). |
| 664 | |
| 665 | Match these uploads to the database inventory before renaming or assigning |
| 666 | dates; resolve duplicate titles explicitly. Export existing transcriptions as |
| 667 | text when wanted, and retain their native source. Do not generate replacement |
| 668 | transcripts as part of copying recordings. |
| 669 | |
| 670 | ## Windows files and dates |
| 671 | |
| 672 | The agreed public layout contains media only. Photos is added after its trial: |
| 673 | |
| 674 | ```text |
| 675 | iCloud Export - 2026-11-04/ |
| 676 | Voice Memos/ |
| 677 | 2025/ |
| 678 | 2025-06-12_212233Z_<id>.m4a |
| 679 | 2026/ |
| 680 | 2026-06-12_212233Z_<id>.m4a |
| 681 | 2026-06-12_212233Z_<id>.qta |
| 682 | Photos/ |
| 683 | 2024/ |
| 684 | 2024-06-12_142233_<uuid>.heic |
| 685 | 2024-06-12_142233_<uuid>.mov |
| 686 | 2024-06-12_142233_<uuid>_edited.jpeg |
| 687 | ``` |
| 688 | |
| 689 | Native sources, catalog snapshots, names, album mappings, sidecars, validation |
| 690 | manifests, and recovery tools stay outside the shared root. No Pilot, Available, |
| 691 | Metadata, native-store, or tool folders belong in the public delivery. |
| 692 | |
| 693 | Preserve HEIC, JPEG, RAW, MOV, MP4, and native audio formats. HEIC/HEVC playback |
| 694 | depends on the Windows apps and installed codecs; test the actual PC. |
| 695 | [Microsoft's HEIF and HEVC guidance](https://support.microsoft.com/en-us/onedrive/upload-heif-and-hevc-photos-and-videos-to-onedrive). |
| 696 | For audio and video, [VLC](https://www.videolan.org/vlc/features.html) is a |
| 697 | useful pilot player. If needed, add separate JPEG or H.264 viewing copies with |
| 698 | the same asset IDs and dates. Preserve the originals; JPEG, stereo mixes, |
| 699 | and video transcodes do not retain every RAW, HDR, depth, or spatial property. |
| 700 | Measure derivative space before converting a whole library. |
| 701 | |
| 702 | Use the Photos catalog's creation date and timezone for photo folders and |
| 703 | mtime, including dates the friend corrected in Photos. Preserve the original |
| 704 | embedded EXIF even when it disagrees; XMP and the inventory carry catalog |
| 705 | corrections. Mtime is a UTC instant, while Windows displays it in the viewer's |
| 706 | timezone. Windows Date created is a separate field and may reflect download |
| 707 | time. Other documents retain their actual modification dates. |
| 708 | |
| 709 | In the restricted recovery store, create a manifest record for every delivered |
| 710 | file with `relative_path`, |
| 711 | `bytes`, `sha256`, and `mtime_utc` as ISO 8601 with an explicit UTC offset. |
| 712 | Link media to logical IDs and variant roles in the inventories. Exclude the |
| 713 | manifest itself from its own listing. Keep paths relative and check case |
| 714 | collisions and Windows path limits. Generate and verify the manifest only |
| 715 | after files and metadata are final. |
| 716 | |
| 717 | The public share’s TAR download preserves UTC recording timestamps to whole |
| 718 | seconds in both archive metadata and a real extraction test. Its URL is the normal share URL |
| 719 | plus `Voice%20Memos/?tar`; the archive contains `Voice Memos/<year>/...` only. |
| 720 | Copyparty’s generated ZIP carries UTC DOS dates and a legacy Unix extra field |
| 721 | that the tested extractor did not honor, shifting extracted mtimes. Use TAR |
| 722 | for the handoff and have the friend verify the resulting Windows dates. |
| 723 | Private evidence: `evidence/tar-time-validation.json`. |
| 724 | |
| 725 | Individual browser downloads may reset filesystem timestamps. Prefer the |
| 726 | verified TAR route and check the friend's actual Windows extraction. Downloads |
| 727 | should use manageable batches or individual-file range requests when necessary. |
| 728 | |
| 729 | ## Snow Globe sharing |
| 730 | |
| 731 | Place portable output under `/srv/clover/Share/iCloud Export - 2026-11-04`, visible |
| 732 | as `/Volumes/clover/Share/iCloud Export - 2026-11-04` on this Mac. Use the existing |
| 733 | [Shares manager and Copyparty](copyparty.md), with a password and read-only |
| 734 | permission scoped to that folder. Keep native app databases, credentials, and |
| 735 | temporary writable uploads outside the read-only delivery link. Retain existing |
| 736 | numeric owners; do not recursively change ownership of Clover's files. |
| 737 | |
| 738 | Create the delivery link after validation. Test its access from a signed-out |
| 739 | client, including denial of parent and sibling folders, a large download, |
| 740 | resume behavior, and the Windows timestamp procedure. For remote uploads of |
| 741 | exceptional memos, use a separate restricted upload folder and revoke that |
| 742 | access after reconciliation. This uses existing services and needs no new |
| 743 | permanent iCloud container. |
| 744 | |
| 745 | ## Direct Photos trial |
| 746 | |
| 747 | [The linked project](https://github.com/boredazfcuk/docker-icloudpd) wraps |
| 748 | `icloudpd` in an Alpine container, adding scheduled downloads, credential and |
| 749 | session storage, notifications, and optional conversions. Its scope is Photos |
| 750 | and videos, including Live Photo components; it does not export Voice Memos |
| 751 | or the whole account. |
| 752 | |
| 753 | Its README still says ADP must be disabled. In contrast, current upstream |
| 754 | `icloudpd` documents `--adp-web-access`, introduced in 1.33.0, with approval |
| 755 | from a trusted device and iCloud web access enabled. This is an upstream |
| 756 | capability, not proof the wrapper image supports that option. Use a pinned |
| 757 | version and prove the actual account flow; the plan does not require disabling |
| 758 | ADP. |
| 759 | [Upstream authentication documentation](https://icloud-photos-downloader.github.io/icloud_photos_downloader/authentication.html). |
| 760 | |
| 761 | For a direct-to-NAS pilot, run upstream in one-time copy mode with private |
| 762 | authentication state. Retrieve original and adjusted assets, RAW alternatives, |
| 763 | and Live Photo components from every wanted library; enumerate Shared Albums |
| 764 | separately. Reconcile asset IDs and all variants. Shared Albums can contain |
| 765 | reduced-resolution copies; obtain originals from their owner where needed. |
| 766 | Regular album membership is not a reason to store the same original repeatedly. |
| 767 | [Upstream features and modes](https://github.com/icloud-photos-downloader/icloud_photos_downloader). |
| 768 | |
| 769 | With upstream **1.33.0**, pass these trial options to the parser inside the |
| 770 | private worker. Account fields come from the restricted file into process memory; |
| 771 | keep credentials out of OS command arguments and keep all tool output private. |
| 772 | The sample and sidecars stay outside the delivery share until verified. |
| 773 | `--recent 30` is only for the trial; remove it for the full run and final |
| 774 | reconciliation. Repeat for each library returned by `--list-libraries`, with a |
| 775 | distinct destination per library. |
| 776 | |
| 777 | ```sh |
| 778 | --adp-web-access \ |
| 779 | --cookie-directory '/srv/clover/.icloud-export-private/2026-11-04/photos-session' \ |
| 780 | --directory '/srv/clover/.icloud-export-private/2026-11-04/Photos trial' \ |
| 781 | --folder-structure '{:%Y}' \ |
| 782 | --file-match-policy name-id7 \ |
| 783 | --live-photo-mov-filename-policy original \ |
| 784 | --size original --size adjusted --size alternative \ |
| 785 | --live-photo-size original \ |
| 786 | --xmp-sidecar \ |
| 787 | --log-level error \ |
| 788 | --recent 30 |
| 789 | ``` |
| 790 | |
| 791 | The repeated sizes request originals and available edits/RAW alternatives. |
| 792 | The ID naming policy distinguishes repeated original filenames. Verify all |
| 793 | IDs and variants, reported creation instants, mtimes, XMP contents, and year |
| 794 | boundaries before accepting this route. Preserve the downloaded names unless |
| 795 | the inventory supplies an unambiguous mapping to a new layout. |
| 796 | [Asset sizes](https://icloud-photos-downloader.github.io/icloud_photos_downloader/size.html) · |
| 797 | [File naming](https://icloud-photos-downloader.github.io/icloud_photos_downloader/naming.html) · |
| 798 | [Command reference](https://icloud-photos-downloader.github.io/icloud_photos_downloader/reference.html). |
| 799 | |
| 800 | Keep cloud-deleting and local-mirroring features disabled: `auto_delete`, |
| 801 | `delete_after_download`, `keep_icloud_recent_only`, and `delete_accompanying`; |
| 802 | leave `keep_icloud_recent_days` unset. The wrapper configuration warns about |
| 803 | filename collisions with flat or year-only download directories. Upstream |
| 804 | documents automatic name de-duplication, so verify the pinned behavior with |
| 805 | duplicate names instead of assuming either statement describes every build. |
| 806 | Normalize to the final year/ID layout only after inventory reconciliation. |
| 807 | Do not rewrite EXIF on archived originals. |
| 808 | [Wrapper configuration](https://github.com/boredazfcuk/docker-icloudpd/blob/master/CONFIGURATION.md). |
| 809 | |
| 810 | ## Finish before canceling |
| 811 | |
| 812 | 1. Reconcile every wanted logical item and its expected files, including edits, |
| 813 | RAW pairs, bursts, Live Photos, hidden items, shared content, and special |
| 814 | recordings. Resolve all missing, empty, corrupt, and failed exports. |
| 815 | 2. Probe all audio/video files and decode-check images; inspect representative |
| 816 | playback on Windows, including long videos and trimmed or layered memos. |
| 817 | Have the friend compare their important items with the source app. |
| 818 | 3. Verify every delivered file's size and SHA-256 on Snow Globe and on the |
| 819 | friend's Windows copy. Check all media mtimes against the inventories, |
| 820 | allowing only the destination filesystem's timestamp precision. |
| 821 | 4. Take a final incremental pass after a short pause in new recordings and |
| 822 | edits, then reconcile new items and regenerate manifests. Keep the native |
| 823 | Mac stores until handoff succeeds. |
| 824 | 5. Establish independently verified copies on separate devices before cloud |
| 825 | deletion. With the native route, retain the Mac source, NAS delivery, and |
| 826 | friend's Windows copy through the deletion. ZFS redundancy is not another |
| 827 | copy, and this repository does not configure automatic snapshot retention. |
| 828 | Before destructive storage cleanup, satisfy [AGENTS.md](../AGENTS.md): |
| 829 | verify application/data recovery and any needed keys from two restricted |
| 830 | off-server copies stored separately. Apply this to relocated Clover data |
| 831 | too; do not count an unverified NAS move as permission to erase its source. |
| 832 | 6. The friend chooses when to stop syncing, remove cloud content, and downgrade. |
| 833 | Confirm remaining use fits the chosen plan and that future backups have a |
| 834 | destination. Never use the downloader to delete automatically during export. |
| 835 | The screenshot also shows 35.7 GB of backups; exporting the two media |
| 836 | categories does not by itself make the account fit the free 5 GB tier. |
| 837 | 7. Sign out inside the export VM or fallback host account. Remove the exact |
| 838 | export device from the friend's trusted devices and revoke downloader |
| 839 | sessions and temporary upload access. Remove the export VM or temporary |
| 840 | host account and native stores after the verified handoff and the recovery |
| 841 | requirements above are satisfied. |
| 842 | |
| 843 | **Deleting synced media can delete it on the friend's other devices.** Apple |
| 844 | also warns that exceeding the downgraded capacity stops iCloud updates and |
| 845 | backups. Keep cancellation and cloud cleanup after verification. |
| 846 | [Synced deletion behavior](https://support.apple.com/en-us/108922) · |
| 847 | [Downgrade consequences](https://support.apple.com/en-us/108318). |
| 848 | |
| 849 | ## Planning verification |
| 850 | |
| 851 | The Mac version, physical disks, APFS allocation, volume quotas/reserves, |
| 852 | snapshot lists, and Snow Globe ZFS availability were read without opening |
| 853 | personal content. OSXPhotos 0.78.0 was run in an isolated temporary tool |
| 854 | environment for `export --help`, `query --help`, and `info --help`; the flags |
| 855 | above exist in that build. Upstream icloudpd 1.33.0 was also checked with |
| 856 | `--help` in isolation, including ADP, asset-size, naming, and XMP options. |
| 857 | The current Cua Driver is 0.38.0; its status and read-only health checks pass |
| 858 | in Clover's login. Passwordless host sudo is unavailable. The devbox was |
| 859 | observed running with Tart 2.41.1; no lifecycle action was taken on it. |
| 860 | Apple's iCloud requirements and license were checked for the VM route. |
| 861 | The dedicated guest has passed command, screen capture/input, read-only |
| 862 | tooling mount, writable transfer, AAC decode, and NAS hash/mtime checks. |
| 863 | Apple sign-in, native sync, the friend's memo schema, and NAS byte/timestamp |
| 864 | checks have passed. Full library reconciliation and the friend's Windows |
| 865 | playback/date check remain required; Clover reports the Windows test has not |
| 866 | yet been performed. |