Skip to content

[AltServer] Fall back to a remote anisette server on macOS 26+ - #1806

Closed
nickclyde wants to merge 2 commits into
altstoreio:classicfrom
nickclyde:altserver-remote-anisette-fallback
Closed

nickclyde wants to merge 2 commits into
altstoreio:classicfrom
nickclyde:altserver-remote-anisette-fallback

Conversation

@nickclyde

@nickclyde nickclyde commented Sep 16, 2026 •

Copy link
Copy Markdown

Summary

Fixes #1751 (AltServer could not retrieve anisette data value "machineID") on macOS 26 and later by falling back to a remote anisette server when AOSKit can't provide anisette data.

Root cause

On macOS 26+, AOSUtilities.retrieveOTPHeadersForDSID: returns an empty dictionary unless the caller holds private entitlements, so AltServer never gets X-Apple-MD-M and every install or refresh fails. The Mail plug-in path fails the same way.

What this does

When both AOSKit and the Mail plug-in fail, AltServer fetches anisette data from a remote anisette server using the same v3 protocol AltStore already uses on-device in "AltServerless" mode. The client is a port of FetchAnisetteDataOperation.swift from the AltStore target, with the on-device specifics swapped for macOS equivalents:

  • Servers come from the published list at cdn.altstore.io/file/altstore/altstore/anisette-servers.json. The first server that works is remembered in preferredAnisetteServerURL so the same provisioned identity keeps being reused.
  • The 16-byte identity and its adi.pb are stored in ~/Library/Application Support/com.rileytestut.AltServer/AnisetteIdentity.json with mode 0600. If a server rejects the cached adi.pb, AltServer re-provisions once.
  • Concurrent requests (for example several AltStore refreshes at once) share a single in-flight fetch, so two provisioning sessions can't race to write the identity file.
  • The device description is rewritten from the Xcode client identity to com.apple.akd/1.0, matching c558994.
  • The whole fallback is gated on macOS 13 since it uses URLSessionWebSocketTask async APIs and RegexBuilder.

Two defaults control the behavior, in the same style as JITTimeout:

defaults write com.rileytestut.AltServer AnisetteServerURL https://ani.sidestore.io
defaults write com.rileytestut.AltServer DisableRemoteAnisette -bool YES

AnisetteError gains three codes (remoteServerUnavailable, remoteServerInvalidResponse, provisioningFailed) with user-facing messages that name the server and a recovery suggestion that mentions the override.

Project file cleanup (separate commit)

6063de6 replaced AltSign-Dynamic with AltSign-Static for AltServer and AltJIT but left the product references on both targets. Xcode re-adds the framework links from those references whenever the workspace is opened, so both products get linked, ldid is built as a standalone dylib, and the build fails with undefined OpenSSL symbols. The first commit removes the two stale references. It stands on its own if you'd rather take it separately.

Design choices worth your review

  • The fallback is on by default. The alternative is a hard failure on every macOS 26+ machine. Happy to add a one-time confirmation before AltServer first contacts a third-party server if you'd prefer that.
  • Identity is stored in a file rather than the Keychain. This avoids keychain prompts on development-signed builds. Switching to the Keychain to match iOS is straightforward if you'd rather.
  • Serial number is the same C02LKHBBFD57 placeholder the AOSKit path and the iOS client already use.

Testing

Tested on an Apple Silicon Mac running macOS 27.0 with an iPhone on iOS 27.0.

  • AOSKit fails, AltServer logs "Falling back to remote anisette server", provisions, and returns headers
  • Install AltStore onto the device succeeds after one Apple ID 2FA prompt
  • Refresh from AltStore (with "Prefer Remote AltServer" off) reuses the persisted identity with no second 2FA prompt

Not yet exercised: the DisableRemoteAnisette and AnisetteServerURL overrides.

Note on building: Xcode 27 refuses the project's MACOSX_DEPLOYMENT_TARGET = 11.0 (minimum is now 12.0). I built with MACOSX_DEPLOYMENT_TARGET=13.0 on the command line and left the project setting alone for you to decide.

Related: #1770 solves the same problem with a bundled Linux VM and also adds an AnisetteServerURL option. This PR is the lighter-weight route and reuses the on-device client instead.

AI usage disclosure

Claude Fable 5.1 (Anthropic) assisted with this change. It reviewed the community workaround at kimziro/altserver-macos27-anisette-fix, ported the on-device v3 client to AltServer, diagnosed the ldid link failure and the stale project references, and drafted this description. I reviewed the code, built it, and ran the tests listed above on my own hardware (MBP M4 Pro on macOS 27, iPhone 14 Pro on iOS 27).

6063de6 replaced AltSign-Dynamic with AltSign-Static for AltServer and AltJIT but left the product references on both targets. Xcode re-adds the framework links from those references whenever the workspace is opened, so both products end up linked, ldid is built as a standalone dylib, and the build fails with undefined OpenSSL symbols.
…provide anisette data

On macOS 26 and later, AOSKit's retrieveOTPHeadersForDSID: returns an empty dictionary unless the caller holds private entitlements, so AltServer fails with "could not retrieve anisette data value machineID" (altstoreio#1751).

When both AOSKit and the Mail plug-in fail, AltServer now fetches anisette data from a remote anisette server using the same v3 protocol AltStore uses on-device. Servers come from AltStore's published list, the first working server is remembered, and the provisioned identity is stored in Application Support so Apple sees the same machine across launches.

Two defaults control the behavior:
- AnisetteServerURL pins a specific server
- DisableRemoteAnisette turns the fallback off
@nickclyde nickclyde mentioned this pull request Sep 16, 2026
@nickclyde

Copy link
Copy Markdown
Author

Closing in favor of fafd76e, which shipped in AltServer 1.8.1. I tested the official 1.8.1 build on macOS 27.0 (M4 Pro) with an iPhone 14 Pro on iOS 27.0: the anisette libraries downloaded on first use, and both installing AltStore and refreshing from the device worked. Local generation is a nicer fix than depending on a third-party server, thanks for getting it out quickly.

Two leftovers in case they're useful:

  • The stale AltSign-Dynamic product references on the AltServer and AltJIT targets (9e51523 in this PR) are still present on classic. They broke my local builds with undefined OpenSSL symbols once Xcode re-added the framework links. Happy to open that as its own small PR if you'd like it.
  • If you ever want a remote anisette server as a backup for when local generation fails on macOS 27, the code here is free to reuse.

@nickclyde nickclyde closed this Sep 17, 2026
rileytestut pushed a commit that referenced this pull request Oct 21, 2026
Add RemoteAnisetteDataFetcher, based on the remote anisette fetcher from
#1806 by Nick Clyde, so AltServer can get anisette data from an anisette
v3 server instead of generating it locally.

- Fetches client_info and user_agent from /v3/client_info and only
  accepts servers whose client_info identifies Windows.
- Provisions a dedicated identity through /v3/provisioning_session.
  The URL bag lookup uses a Mac client info; the provisioning requests
  use the server's Windows client info. The identity is stored in
  RemoteAnisetteWindows/identity.json, separate from AnisetteKit's.
- Re-provisions once when the server reports -45061 and supports
  resynchronizing with X-Apple-I-MD-DATA.
- Defaults to https://ani.jkcoxson.com; can be overridden with the
  AnisetteServerURL user default.

Adds remoteServerUnavailable, remoteServerInvalidResponse and
provisioningFailed errors to AnisetteError.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant