Add local network permission handling for private CalDAV servers

[patrickunterwegs]

Summary

Android 17 (API 37) moved local network access behind the android.permission.ACCESS_LOCAL_NETWORK runtime permission; below that it came for free with INTERNET. Since targetSdk is 37, adding a CalDAV account on a LAN address silently failed — denied TCP connects don't fail fast, they time out, so the app looked broken rather than blocked.

Reproduced against a self-hosted Radicale: the phone's browser reached http://192.168.1.21:5232 fine while the app timed out after 10s, and on the same device targetSdk 36 connected where 37 did not.

What changes for the user

Adding an account always runs discovery, permission or not. Nothing is gated or held back: someone pointing the app at a LAN server can read the timeout and act on it.

What's new is a notice under the server field, shown only when the entered host is on a private network and only while that field isn't being typed in, saying whether local network access is granted, plus a Manage permission button:

• Not granted — asks the OS, since that's the one state it may still be willing to prompt for.
• Granted — opens app settings, the only place a grant can be revoked.
• Unknown (iOS) — opens app settings; iOS has nothing to ask through.

Once Android has refused twice it stops showing the dialog and launch() returns denied immediately without prompting. The button detects that (no rationale will be shown) and opens the settings page instead, so it never looks dead.

Implementation

Two types, split by what each one needs. PermissionChecker (status, openAppSettings) works off an application context, so PlatformPermissionChecker is injected through Koin like the other platform services. PermissionRequester (request) can't be: on Android the prompt goes through an ActivityResultLauncher, which must be registered against the Activity before it reaches STARTED and is torn down with it — so it stays a @Composable expect fun rememberPermissionRequester, the shape rememberImagePicker and rememberFilePicker already use for the same reason.

Per platform — Android does the real check and prompt; iOS reports UNKNOWN and can only open settings, since its own prompt is raised implicitly on the first LAN connection and can't be queried; Desktop and Web report NOT_APPLICABLE and show no permission UI at all.

The Android side references the permission as a string literal and the version gate as the numeric 37 rather than a Build.VERSION_CODES constant — Google's own documentation sample names the wrong one, and a misnamed constant compiles into a check that never fires.

isPrivateNetworkHost (LocalNetworkAddress.kt) decides when any of this is worth mentioning: IPv4 10/8, 172.16/12, 192.168/16, 169.254/16, 127/8; IPv6 fc00::/7, fe80::/10, ::1 and IPv4-mapped forms; .local and single-label hostnames including localhost. It matches on the literal host, so a DNS name pointed at a private range isn't recognised — resolving would need a lookup before the UI could render, and the cost is a missed hint, not a broken connection. Covered by LocalNetworkAddressTest, including the boundaries that must stay public (172.15.x, 172.32.x, 192.169.x).

Credentials without a username and password. Credentials no longer requires them, so read-only collections on servers that don't authenticate can be subscribed to. This was needed to read the host off credentials as the single source of truth, and is a genuine feature in its own right. All 17 basicAuth call sites are now guarded by hasUsernameAndPassword() — sending Basic base64(":") would make some servers reject requests they'd otherwise serve anonymously. The server field stays labelled optional; such servers are rare enough that trying is expected to be enough.

Declarations: ACCESS_LOCAL_NETWORK in the three Android manifests, and NSLocalNetworkUsageDescription in the three iOS Info.plist files. iOS already prompted and worked without the key — it supplies the purpose string shown inside that prompt, is effectively mandatory on iOS 18+, and is required for App Store review.

Testing

Verified on device: the Android 17 phone that reproduced the timeout now connects after granting, and an anonymous server works. CI (:shared:allTests plus lintDebug on all three app modules) is green.

Not covered by tests: hasUsernameAndPassword() and the permission state machine are verified by reading and on-device use rather than by CI. The iOS target is not built by this workflow, so PermissionChecker.ios.kt is only checked by compiling the shared framework locally.

Known limitations

• On an anonymous account, "update password" is silently ineffective — the rebuilt credentials keep the blank username, and that sheet has no username field. Accepted for now.
• After a permanent denial, dismissing the permission dialog with Back is indistinguishable from it never being shown, so that also lands in app settings.