steilerDev/icloud-photos-sync v5.0.0

on GitHub

5.0.0 (2026-10-09)

⚠ BREAKING CHANGES

• The Influx field of MFA warnings is renamed from
  warn-mfa_resend_error to warn-mfa_error - update queries and dashboards
  using the old name.

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

• Boolean options configured through environment
  variables are only enabled for the values true, 1, yes or on. Values
  like false, 0, no, off or an empty value now disable the option (they
  previously enabled it), any other value fails the startup.

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

• HTTP_PROXY/HTTPS_PROXY/NO_PROXY are no longer applied
  implicitly. Set --use-system-proxy (USE_SYSTEM_PROXY=true) to route
  requests through the configured proxy.
• The Docker image is based on Docker Hardened Images and no longer includes a shell, package manager or other system utilities. docker exec -it <container> sh is no longer possible - commands of this application can still be executed directly (e.g. docker exec -it <container> icloud-photos-sync token), use docker debug to debug the container. The application still runs with UID 100 and GID 101, however the default library path /opt/icloud-photos-library is no longer world-writable, but owned by this user.
• Node.js >= 26 is required when installing through npm.

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

Features

• monitoring: #1008 Prometheus Compatible Metrics Endpoint (6e8a7a4)
• [app] follow cloudkit continuation markers when paging queries (ef696c3), closes #364
• [app] move deleted assets into a trash folder with soft delete (a84e1f3), closes #314
• [app] read AppleID credentials from files via APPLE_ID_USER_FILE/APPLE_ID_PWD_FILE (57b2864), closes #1000
• [app] rework prometheus exporter for spec compliance and alerting (f6881cf), closes #1008
• [app] support Node.js permission model & shell-free crash reporting (55f9b66), closes #1116 #1119
• [app] sync hidden photos with --sync-hidden (1ec2146), closes #558
• [docker] build image on Docker Hardened Images (fd73d7d), closes #1119
• [docker] Docker image no longer provides a shell (bb254cc), closes #1119

Bug Fixes

• [app] abort sync on file system errors while writing assets (b38b26d)
• [app] add support for wav files (77d9368), closes #143
• [app] apply asset modification time within the download queue (95e123b)
• [app] count received positions by assets only (69374aa), closes #364
• [app] detect icloud accounts requiring an action on icloud.com (940440d), closes #1071
• [app] detect library locks held by processes in other containers (b1bdc4b)
• [app] exit with code 0 on help/version and draw banner line without terminal width (4ffb209), closes #1123
• [app] export WRITE_ALBUMS_STARTED status in influx metrics (2e13a93)
• [app] finish scheduled syncs of empty libraries (e93b922)
• [app] forward nonFTEU flag when requesting sms/voice mfa code (a9c7b59)
• [app] include cloudkit error details in failed photos requests (46ab637), closes #1071
• [app] keep syncing large libraries when download urls expire (f351477), closes #871
• [app] keep web base path when redirecting to the state view (e0f1840)
• [app] mask health check url, push endpoints and url credentials in crash reports (344e8bf)
• [app] mask session headers and cookies in crash reports (2a5ed34)
• [app] name influx warning fields after the runtime warning events (45bac9e)
• [app] parse the value of boolean environment variables (a8f9a42)
• [app] render web ui log incrementally (bce23a0), closes #1071
• [app] replace axios-har-tracker with built-in network capture (96edd8a), closes #1114
• [app] restore MFA flow for iOS 26.4+ (e06da11), closes #1071 #1007 #1103 #1104
• [app] scheduled syncs and Web UI re-authentication failing with APP_NOT_READY (2929f60)
• [app] stop orphaned photos requests from crashing a failed sync (8362d86), closes #1071
• [app] surface errors while loading trusted phone numbers (56a6d15)
• [app] surface photos setup errors on reconnect instead of timing out (dfcfb69), closes #1071
• [app] wait and retry throttled cloudkit requests (69a1f28), closes #1071
• [app] workaround iOS 26.4 MFA by switching default to SMS (5b803f2), closes #1007
• add missing EOL to Prometheus metrics (1dc73bb)
• Correctly reading resource file instead of overwriting (f7454e2)
• disable buggy state check (c9ed864)
• state metric may not be string (1901e3c)
• use 'account ready' as event for authentication done (5dd17a9)
• whitespace related issues (7a20033)

Code Refactoring

• [app] dependency-free SRP implementation matching Apple's web client (4ee837b)
• [app] replace axios with node's built-in fetch (99f0a05), closes #1115
• [app] replace small dependencies with Node built-ins & adopt Node 26 features (db47db2)
• [app] require schema validation for every response (d76a28f)
• [app] validate health check pings as plain text (9f95243), closes #1115
• Move library locking logic into state (3e6d9c0)

Tests

• [app] add soft delete options to docker help output (bbc9291)
• [app] add use-system-proxy option to expected help output (3336ee2)
• [app] align web server tests with SMS default MFA method (eb69a5a)
• [app] allow more time for scheduling tests on slow runners (03fd090)
• [app] cover prometheus metrics exporter and endpoint (8805eb2), closes #1008
• [app] replace mock-fs with a real file system based helper (3cc834b)
• [app] replace todo placeholders and cover icloud-photos module (a193e39)
• [app] update expected help text to current documentation links (aadcff7)
• [docker] await help output assertion & update expected text (4f0f9ba)

CI Pipeline

• [docker] drop Docker Scout recommendations (da1dce2)
• Add timeout and manual trigger to API monitor workflow (9bfa087)
• Fix workflow_dispatch condition for API monitor (808ca81)
• move semantic-release dependencies back into prepare-semantic-release (baafda7), closes #1045 #1052
• open a pr to merge main into dev after production release (9bfd688), closes #1122
• re-enable scheduled API monitor (3a96f3f)
• refresh GitHub Actions, relocate release dependencies & rework Dependabot (7c91666)
• remove unsupported semver cooldown from github-actions dependabot config (d2d20eb)
• Removed caching from docker release action (48509aa)
• run trust token container as the invoking user (e602aff)
• run unit tests before releasing from push and pause API monitor schedule (79ad2d6)
• skip coverage collection in macos unit tests (e57bc55)

Maintenance

• [app] bump jsonc from 2.0.0 to 3.0.0 (546abf9), closes #1114
• [app] security & drop-in dependency upgrades (167e009)
• [app] TypeScript 6 in strict mode, commander 15, inquirer 8 (b3ef080)
• [docs] bump mkdocs dependencies and Python to 3.13 (4c753fe)
• [docs] freeze docs toolchain instead of migrating off material (48b57c3), closes #1118
• bulk upgrade all dependencies (a570716)
• upgrade runtime to Node 26 (33d7e72)

Documentation

• [docs] document download url expiry and file checksum format (341db8c)
• add CLAUDE.md with build, test and architecture guidance (116372d)
• add issue class/status label rules to CLAUDE.md (9789b7d)
• add rule to remove worktrees after their PR is merged (1df0b49)
• add v5 upgrade guide and node 26 requirement (9c0ce43), closes #1121
• also delete the remote branch after a PR is merged (cd30c8d)
• define status label meanings in CLAUDE.md (c509684)
• describe the library lock heartbeat and harmonized warning names (c775607)
• document adp account in CLAUDE.md (b3898f1)
• document backtrace error report api in CLAUDE.md (ea4b21e)
• document IP-bound, co-existing trust tokens and why CI needs a residential runner (3b181fd)
• document prometheus metrics endpoint (8172efa), closes #1008
• document runtime hardening & building the Docker image (de58a58), closes #1116
• drop dedicated v5 upgrade guide (780723f)
• expand CLAUDE.md with iCloud API surface, CI map, coding style and secrets handling (2dc3f49)
• fix outdated statements in CLAUDE.md (66e667e)
• map the full icloud api surface in api.md (7ad2264)
• note dev as worktree base branch in CLAUDE.md (7ac948f)
• note roughly 30 day trust token lifetime (0f589f3)
• note that the prod account receives MFA via trusted device push (47bda51)
• refer to a mirrorless camera in the motivation (94cfd8a)
• run API and full Docker tests with the stored test account credentials (e8c38e5)
• store adp and prod trust tokens in their env files (7feff40)
• update developer docs and contributing guide (ce2a459)
• update user guides to match v5 behaviour (a787d98)