hstratus-auth — authentication for iCloud services
hstratus-auth authenticates with iCloud using Apple ID credentials stored on
disk. The full sign-in flow — SRP credential exchange followed by any required
two-factor (2FA) or legacy two-step (2SA) challenge — runs automatically,
prompting the user for verification codes when needed. On success, it caches
a session token for use with other iCloud services.
Disclaimer — use at your own risk
- This library is unofficial and not supported by Apple.
- The iCloud authentication protocol it uses is undocumented and may change
without notice.
Usage
The same two steps — saving credentials and authenticating — are available
programmatically.
Saving credentials
Write a credentials.json file directly, or call saveCredentials:
import Network.HStratus.Session (Credentials (..), saveCredentials)
saveCreds :: IO ()
saveCreds =
saveCredentials $ Credentials
{ accountName = "[email protected]"
, password = "your-password"
}
Authenticating
Create an Api handle with mkApi, then call login:
import Network.HStratus.Http (mkApi, login, AuthState (..))
import Network.HStratus.Http.Endpoints (Realm (..))
example :: IO ()
example = do
api <- mkApi Usual -- or China for mainland China accounts
result <- login api
case result of
Authenticated _session _accountData -> putStrLn "Authenticated!"
_ -> putStrLn "Unexpected result"
Injectable callbacks
Pass your own callbacks to loginWith to replace the interactive prompts —
useful in automation or tests. The snippet below shows the code-reader; the
phone-selector and device-selector arguments follow the same pattern.
import Network.HStratus.Http (loginWith)
import qualified Data.Text.IO as Text
exampleWith :: Api -> IO AuthState
exampleWith api = loginWith readCode (\_ -> pure Nothing) chooseDevice api
where
readCode codeLen = do
Text.putStrLn $ "Enter the " <> Text.pack (show codeLen) <> "-digit code:"
Text.getLine
chooseDevice (d :| _) = pure d
If you already hold a Requires2FA or Requires2SA value from a prior call,
resume with completeTwoFactor / completeTwoFactorWith or complete2SA /
complete2SAWith.
Reauthentication
The session token expires after a period set by iCloud (approximately two months
at the time of writing). When it does, authenticate again to refresh it.
CLI usage
A command-line interface using this behaviour is provided by the hstratus
package. Use hstratus auth init and hstratus auth login to save credentials and authenticate.
Apple and the Apple logo are trademarks of Apple Inc., registered in the U.S. and other countries and regions.
iCloud is a service mark of Apple Inc., registered in the U.S. and other countries and regions.
