Activation Kit

Automated iOS device activation and supervision toolkit. This package uses pymobiledevice3 and USB device detection to automatically supervise iOS devices when connected.

Features

• 🔌 Automatic detection - Detects iOS devices when connected via USB
• 🔧 Automated supervision - Automatically supervises devices with your organization
• ⚡ Setup skipping - Configures devices to skip all setup assistant screens
• 🌍 Language/locale - Pre-configures language and locale settings
• 📡 Event-driven - Subscribe to activation events for monitoring

Prerequisites

1. Install pymobiledevice3:

   pip install -U pymobiledevice3

2. Install iTunes (Windows only): Download and install iTunes from Microsoft Store for USB device support.

3. Run as Administrator (Windows) or with sudo (macOS): Some pymobiledevice3 commands require elevated privileges.

4. Configure WiFi credentials (for MDM enrollment): Copy .env.example to .env and fill in your WiFi network credentials:

   cp .env.example .env
   # Edit .env with your WiFi SSID and password

Installation

npm install @mcesystems/activation-kit

Quick Start

import { ActivationKit } from "@mcesystems/activation-kit";

// Create activation kit with your organization name
// This should match your enterprise certificate name
const activationKit = new ActivationKit({
  organizationName: "Your Company Name",
  language: "en",
  locale: "en_US",
  autoErase: true, // Erase device before supervision
});

// Listen for events
activationKit.onEvent((event) => {
  switch (event.type) {
    case "state_changed":
      console.log(`[${event.udid}] State: ${event.previousState} → ${event.newState}`);
      break;
    case "activation_completed":
      console.log(`Device activated: ${event.udid}`);
      break;
    case "activation_failed":
      console.log(`Activation failed: ${event.error}`);
      break;
  }
});

// Activate multiple devices by UDID (each assigned logical port 1, 2, 3...)
await activationKit.activateAll([
  "00008101-000C68290269001E",
  "00008101-000123456789ABCD",
  "00008101-000AABBCCDDEEFF0",
]);

// Or activate a single device
await activationKit.activate("00008101-000C68290269001E");

// Get device states
const allStates = activationKit.getAllDeviceStates();
const singleState = activationKit.getDeviceState("00008101-000C68290269001E");

Configuration

interface ActivationConfig {
  // Organization name for supervision (must match your certificate)
  organizationName: string;

  // Language code (default: "en")
  language?: string;

  // Locale code (default: "en_US")
  locale?: string;

  // Timeout for device reboot in ms (default: 120000)
  rebootTimeout?: number;

  // Timeout for each command in ms (default: 30000)
  commandTimeout?: number;

  // Auto-erase device before supervision (default: true)
  autoErase?: boolean;

  // Path to Python executable (default: "python")
  pythonPath?: string;
}

Events

The onEvent callback receives events during the activation process:

| Event Type | Description | |------------|-------------| | device_connected | iOS device connected via USB | | device_disconnected | iOS device disconnected | | state_changed | Device activation state changed | | activation_started | Activation process started | | activation_completed | Device successfully activated | | activation_failed | Activation process failed | | command_output | Output from pymobiledevice3 command |

Device States

| State | Description | |-------|-------------| | disconnected | Device not connected | | connected | Device connected, ready for activation | | erasing | Device is being erased | | waiting_for_reboot | Waiting for device to reboot | | supervising | Applying supervision configuration | | configuring | Setting language/locale | | ready | Device is activated and ready | | error | Activation failed |

Environment Variables

The example script (src/examples/activate-device.ts) supports loading configuration from a .env file. Create a .env file in the package directory (copy from .env.example) with your settings:

WiFi Configuration (required for MDM enrollment)

# Required: WiFi network name
WIFI_SSID=YourNetworkName

# Required: WiFi password
WIFI_PASSWORD=YourPassword

# Optional WiFi settings
WIFI_ENCRYPTION=WPA2          # WPA2, WPA3, WEP, None
WIFI_HIDDEN=false              # true for hidden networks
WIFI_ENTERPRISE=false          # true for 802.1X enterprise
WIFI_USERNAME=                 # Username for enterprise auth
WIFI_EAP_TYPE=PEAP             # EAP type for enterprise

# Alternative: Use existing profile file
WIFI_PROFILE_PATH=C:\path\to\WifiN.mobileconfig

MDM Configuration

MDM_ENDPOINT=https://api-v5.mce-sys.com/mdm/graphql
MDM_AUTH_TOKEN=your-token-here  # Auto-fetched if not provided
MDM_CERT_BASE64=base64-cert     # Enterprise certificate for auto-trust
MDM_APP_ID=com.example.app      # App bundle ID to install
MDM_APP_URL=https://example.com/app.ipa

Note: The .env file is gitignored and will not be committed to version control.

Scripts

Create Local IPA Manifest

For testing with a local IPA file, use the create-local-manifest.ts script to generate a manifest.plist:

# Basic usage
npx tsx scripts/create-local-manifest.ts path/to/app.ipa

# With custom host and port
npx tsx scripts/create-local-manifest.ts path/to/app.ipa --host 192.168.1.100 --port 8000

# With bundle ID and version
npx tsx scripts/create-local-manifest.ts path/to/app.ipa --bundle-id com.example.app --version 2.0.0

This will:

1. Create a manifest.plist file in the same directory as your IPA
2. Generate URLs pointing to your local HTTP server
3. Provide instructions for starting a local server

Example workflow:

# 1. Create manifest
npx tsx scripts/create-local-manifest.ts app.ipa --host 192.168.1.100 --port 8000

# 2. Start HTTP server in the IPA directory
cd /path/to/ipa/directory
python -m http.server 8000

# 3. Use the manifest URL in Postman or .env file
# MDM_APP_URL=http://192.168.1.100:8000/app-manifest.plist

Options:

• --host <ip> - Local IP address or hostname (default: localhost)
• --port <port> - HTTP server port (default: 8000)
• --bundle-id <id> - Bundle identifier (default: auto-generated from filename)
• --version <ver> - Bundle version (default: 1.0.0)
• --title <name> - App title (default: filename)
• --output <path> - Output manifest file path (default: same dir as IPA)

Activation Flow

When a device is connected, the following steps are performed:

1. Check current state - Verify if device is already supervised with correct organization
2. Erase device (if autoErase: true) - Wipe the device to clear existing configuration
3. Wait for reboot - Wait for device to restart after erase
4. Supervise device - Apply supervision with organization name and skip-setup configuration
5. Install WiFi profile (if configured) - Install WiFi configuration for internet connectivity
6. Configure settings - Set language and locale
7. Pair device - Establish trust with the computer
8. Activate - Perform iCloud activation
9. MDM Enrollment (if configured) - Enroll device in MDM, install profiles and apps
10. Restart - Restart device to apply all settings

Direct pymobiledevice3 Access

You can also use the pymobiledevice3 wrapper functions directly:

import {
  listDevices,
  eraseDevice,
  superviseDevice,
  setLanguage,
  setLocale,
  restartDevice,
  getCloudConfiguration,
} from "@mcesystems/activation-kit";

// List connected devices
const devices = await listDevices();
console.log(devices);

// Erase a device
await eraseDevice("00008101-000C68290269001E");

// Supervise a device
await superviseDevice("00008101-000C68290269001E", "Your Org Name");

// Set language and locale
await setLanguage("00008101-000C68290269001E", "en");
await setLocale("00008101-000C68290269001E", "en_US");

// Restart device
await restartDevice("00008101-000C68290269001E");

// Check cloud configuration
const config = await getCloudConfiguration("00008101-000C68290269001E");
console.log(config?.IsSupervised);

Troubleshooting

"Organization name mismatch"

The organization name in the configuration must exactly match your enterprise certificate name. Check the certificate name in Keychain (macOS) or the app signing details.

"Device did not reappear after erase"

• Ensure the device is properly connected
• Try increasing rebootTimeout
• Check USB cable and port

"Failed to supervise device"

• Run as Administrator (Windows) or with sudo (macOS)
• Ensure the device has no existing cloud configuration, or use autoErase: true

"pymobiledevice3 not found"

• Install it: pip install -U pymobiledevice3
• Verify Python is in PATH
• Try setting explicit pythonPath in configuration

License

MIT