@limrun/ui 0.13.3-rc.1 → 0.13.4

package/src/device-install/README.md

@@ -0,0 +1,423 @@
+# Install to a real iPhone over WebUSB
+
+Build a signed iOS app on Limrun and install it onto a physical iPhone that's
+plugged into the user's own computer — straight from the browser, no Mac and no
+Xcode on their machine. The browser talks to the iPhone over WebUSB; Limrun runs
+the native pairing and install (`libimobiledevice`) on its side and relays the
+USB traffic over a WebSocket.
+
+`@limrun/ui` ships the browser primitives and React hooks; your app owns the UI.
+There is no prebuilt wizard, so you decide how much of the Apple Developer flow
+to expose and how the steps look in your product.
+
+The flow:
+
+1. **Provision** an Xcode build sandbox and get its `apiUrl` + `token`.
+2. **Pair** the iPhone over WebUSB (the user taps _Trust_ once).
+3. **Get signing assets** — upload a `.p12` + `.mobileprovision`, or sign in with
+   an Apple ID and let Limrun fetch them.
+4. **Build** a signed `iphoneos` IPA on the sandbox; logs stream back.
+5. **Install** the IPA onto the paired iPhone over the WebUSB relay.
+
+> **Want to see it working first?** A complete, runnable reference app — with the
+> upload and Apple Developer signing flows, a status stepper, and error handling —
+> lives in [`src/device-install/demo`](./demo). Read its
+> [`demo.tsx`](./demo/demo.tsx) end to end to see how every hook and helper in this
+> guide fits together, or run it locally (see [Run the demo](#run-the-demo)).
+
+## Requirements
+
+- A **Chromium** browser (Chrome or Edge). WebUSB is not available in Safari or
+  Firefox.
+- A **secure context** — your app must be served over `https://` or `localhost`.
+- A physical iPhone connected over USB; the user unlocks it and taps **Trust**
+  during pairing.
+- An Apple signing identity: a development `.p12` (with its private key) and a
+  `.mobileprovision` that covers the app's bundle ID **and** the target device's
+  UDID. See [Apple signing](#get-signing-assets).
+
+## Install
+
+```bash
+npm install @limrun/ui
+```
+
+The feature is split across three subpath entry points so you only pull in what
+you use:
+
+| Import                                  | Provides                                                                                            |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `@limrun/ui/device-install` + `/react`  | WebUSB device selection, pairing, install relay, pair-record storage (`useDeviceInstallRelay`).     |
+| `@limrun/ui/device-build` + `/react`    | Signing-asset import/validation, signed-build trigger, log streaming (`useDeviceBuild`).            |
+| `@limrun/ui/app-store-relay` + `/react` | Apple ID login (SRP + 2FA) and Apple Developer Portal calls (`useAppleIDLogin`, `list*`/`create*`). |
+
+## Get a build sandbox
+
+Every call below takes an `apiUrl` and `token` that point at a Limrun Xcode
+sandbox. Provision one with the `@limrun/api` SDK or the CLI, then read them off
+the instance status — see [Build with remote Xcode](https://docs.limrun.com/docs/ios/build-with-xcode).
+
+```ts
+import Limrun from '@limrun/api';
+
+const lim = new Limrun({ apiKey: process.env['LIM_API_KEY'] });
+const xcode = await lim.xcodeInstances.create({ wait: true, reuseIfExists: true });
+
+const apiUrl = xcode.status.apiUrl; // HTTP base for the sandbox
+const token = xcode.status.token; // per-instance bearer
+```
+
+The sandbox must have your project **synced** before a build runs (`lim xcode build .`
+or `lim xcode sync .`). A build against an empty sandbox returns
+`no synced folder found; call /sync first`.
+
+The `token` is an **instance-scoped** bearer, not your org API key. It's safe to hand to the browser for this one sandbox; it can't touch the rest of your account.
+
+## Pair the iPhone
+
+`useDeviceInstallRelay` drives the WebUSB side. `requestUSBAccess` opens the
+browser's device picker; `pairBrowser` runs the pairing handshake through the
+relay and stores the resulting pair record in the browser's IndexedDB, so the
+user only taps **Trust** once per device.
+
+```tsx
+import { useDeviceInstallRelay } from '@limrun/ui/device-install/react';
+
+const install = useDeviceInstallRelay({ apiUrl, token, log: (m, d) => console.log(m, d) });
+
+// 1. Pick the iPhone (shows Chrome's WebUSB chooser).
+await install.requestUSBAccess();
+// install.device?.hello.serialNumber is the UDID.
+
+// 2. Pair (user unlocks + taps Trust). Stored for next time.
+await install.pairBrowser();
+// install.hasPairRecord === true
+```
+
+| Field / method                             | Use                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| `requestUSBAccess()`                       | Open the WebUSB picker and select the iPhone.                      |
+| `pairBrowser()`                            | Pair through the relay; persists the pair record.                  |
+| `startInstallation()`                      | Install the latest signed build onto the paired device.            |
+| `device`                                   | Selected device; `device.hello.serialNumber` is the UDID.          |
+| `hasPairRecord` / `canPair` / `canInstall` | Gating flags for your buttons.                                     |
+| `busyAction`                               | `'usb'`, `'pair'`, or `'install'` while an operation is in flight. |
+| `error`                                    | Last error message, if any.                                        |
+
+Pairing is independent of the build — you can pair before signing or building.
+Only `startInstallation()` needs both a stored pair record and a successful
+build.
+
+## Get signing assets
+
+A real-device install must be signed. You produce a `StoredSigningAssets` object
+(persisted in IndexedDB) one of two ways, then hand it to the build step.
+
+### Option A — upload files (simplest)
+
+Ask the user for a `.p12` (with its private key), its password, and a
+`.mobileprovision`. `importSigningAssetsFromFiles` validates the profile against
+the bundle ID and device, then stores it.
+
+```tsx
+import { importSigningAssetsFromFiles } from '@limrun/ui/device-build';
+
+const assets = await importSigningAssetsFromFiles({
+  certificateFile, // File (.p12)
+  provisioningProfileFile, // File (.mobileprovision)
+  certificatePassword,
+  bundleId, // e.g. 'com.example.MyApp'
+  deviceUDID: install.device?.hello.serialNumber,
+  signingMode: 'development',
+});
+```
+
+### Option B — sign in with Apple ID
+
+For a guided experience with no files to find, use the App Store Connect relay.
+The user's password never leaves the browser: the SRP proof is computed
+client-side and the relay only forwards Apple's auth and provisioning requests.
+
+```tsx
+import { useAppleIDLogin } from '@limrun/ui/app-store-relay/react';
+import {
+  registerAppleDevice,
+  listAppleCertificates,
+  createAppleCertificate,
+  downloadAppleCertificate,
+  exportAppleCertificateP12,
+  generateAppleSigningKeyAndCSR,
+  createAppleProfile,
+  downloadAppleProfile,
+} from '@limrun/ui/app-store-relay';
+import {
+  getLatestSigningAssetsWithCertificate,
+  parseProvisioningProfileBase64,
+  putAppleGeneratedSigningAssets,
+} from '@limrun/ui/device-build';
+
+const appleLogin = useAppleIDLogin({ limbuildApiUrl: apiUrl, token });
+const session = await appleLogin.startLogin({ accountName, password });
+if (session?.requiresTwoFactor) await appleLogin.submitTwoFactorCode(code);
+
+// Resolve the team id across all three fields Apple may use.
+const teamId = team.teamId ?? String(team.providerId ?? team.publicProviderId ?? '');
+const base = { apiUrl, token, appleSessionId: appleLogin.session!.appleSessionId, teamId };
+
+// Register the paired iPhone (no-op if already registered).
+await registerAppleDevice({ ...base, deviceUDID, name: 'My iPhone' });
+
+// Reuse a stored cert if its key is in this browser and it's still current;
+// otherwise mint a new one.
+let certificateId: string | undefined;
+let certificateP12Base64: string | undefined;
+const stored = await getLatestSigningAssetsWithCertificate(teamId, 'development');
+if (stored?.certificateID && stored.certificateP12Base64) {
+  const current = await listAppleCertificates({ ...base, certificateKind: 'development' });
+  const match = current.find(
+    (c) => c.certificateId === stored.certificateID || c.certRequestId === stored.certificateID,
+  );
+  if (match) {
+    certificateId = (match.certificateId as string) ?? stored.certificateID; // canonical id
+    certificateP12Base64 = stored.certificateP12Base64;
+  }
+}
+if (!certificateId) {
+  const key = await generateAppleSigningKeyAndCSR({ commonName: 'My App' });
+  const created = await createAppleCertificate({
+    ...base,
+    certificateKind: 'development',
+    csrPEM: key.csrPEM,
+  });
+  certificateId = (created?.certificateId as string) ?? (created?.certRequestId as string);
+  const cer = await downloadAppleCertificate({ ...base, certificateKind: 'development', certificateId });
+  certificateP12Base64 = exportAppleCertificateP12({
+    privateKeyPKCS8Base64: key.privateKeyPKCS8Base64,
+    certificateBase64: cer.rawBodyBase64!,
+    password: certificatePassword,
+  });
+}
+
+// Create a profile covering the bundle ID + device (unique name avoids
+// "multiple profiles with the same name"), download it, and store everything.
+const profile = await createAppleProfile({
+  ...base,
+  profileKind: 'development',
+  bundleId,
+  appIdId,
+  certificateIds: [certificateId],
+  deviceIds: [appleDeviceId],
+  name: `MyApp ${Date.now()}`,
+});
+const profileId = (profile?.provisioningProfileId as string) ?? (profile?.profileId as string);
+const downloaded = await downloadAppleProfile({ ...base, profileId });
+
+const assets = await putAppleGeneratedSigningAssets({
+  bundleID: bundleId,
+  deviceUDID,
+  teamID: teamId,
+  signingMode: 'development',
+  certificateID: certificateId,
+  certificateP12Base64: certificateP12Base64!,
+  certificatePassword,
+  provisioningProfileBase64: downloaded.rawBodyBase64!,
+  profile: parseProvisioningProfileBase64(downloaded.rawBodyBase64!),
+});
+```
+
+These are Apple's rules, not Limrun's, and each one is a common dead end:
+
+| Rule                                                     | Consequence if ignored                                                                                                                          |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| A cert is useless without its private key.               | You can only sign with a cert this browser created (and stored) or one imported as `.p12`. Apple never returns private keys.                    |
+| Max **2** development certs per team.                    | Creating one per build fails with _"you already have a current Development certificate"_. Reuse, or revoke an old one to free a slot.           |
+| Profile creation needs the canonical `certificateId`.    | Passing a `certRequestId` fails with _"no current certificates matching the provided certificate IDs"_. Resolve it via `listAppleCertificates`. |
+| A revoked cert still appears in lists.                   | Signing with it builds fine but the device rejects install with `ApplicationVerificationFailed`. Treat revoked certs as unusable.               |
+| The team id may live in `providerId`/`publicProviderId`. | Reading only `teamId` leaves the flow stuck after sign-in.                                                                                      |
+| Profiles are device-scoped and immutable.                | To authorize a new device you regenerate the profile (see [Adding a device](#add-a-device-to-a-profile)).                                       |
+
+## Build a signed IPA
+
+`useDeviceBuild` triggers a signed `iphoneos` build on the sandbox and streams
+the logs. It builds for the device SDK and signs with the assets you pass.
+
+```tsx
+import { useDeviceBuild } from '@limrun/ui/device-build/react';
+
+const build = useDeviceBuild({ apiUrl, token, signingAssets: assets });
+
+await build.startBuild({ signingAssets: assets });
+// build.status: 'idle' | 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled'
+// build.logs: BuildLogLine[]  (render line.data; xcodebuild lines can be long — wrap them)
+```
+
+| Field / method                  | Use                                                                 |
+| ------------------------------- | ------------------------------------------------------------------- |
+| `startBuild({ signingAssets })` | Kick off the signed device build; returns the exec id.              |
+| `status`                        | Build lifecycle state. `succeeded` gates install.                   |
+| `logs`                          | Streamed `command` / `stdout` / `stderr` lines.                     |
+| `error`                         | Set (and `status` → `failed`) if the build or its log stream fails. |
+
+## Install over WebUSB
+
+Once the build succeeds and the device is paired, install:
+
+```tsx
+await install.startInstallation();
+```
+
+Progress streams through your `log` callback. The relay surfaces the device's
+real reason on failure (for example
+`Install error: ApplicationVerificationFailed — The identity used to sign the executable is no longer valid.`),
+so render the log — it's the fastest way to diagnose a signing/profile mismatch.
+
+## Full example
+
+A single component covering pair → upload signing → build → install. It assumes
+you already have `apiUrl`, `token`, and a `bundleId`.
+
+```tsx
+import { useState } from 'react';
+import { importSigningAssetsFromFiles, type StoredSigningAssets } from '@limrun/ui/device-build';
+import { useDeviceBuild } from '@limrun/ui/device-build/react';
+import { useDeviceInstallRelay } from '@limrun/ui/device-install/react';
+
+export function InstallToIPhone({
+  apiUrl,
+  token,
+  bundleId,
+}: {
+  apiUrl: string;
+  token?: string;
+  bundleId: string;
+}) {
+  const [certificateFile, setCertificateFile] = useState<File>();
+  const [profileFile, setProfileFile] = useState<File>();
+  const [certificatePassword, setCertificatePassword] = useState('');
+  const [signingAssets, setSigningAssets] = useState<StoredSigningAssets>();
+  const [log, setLog] = useState<string[]>([]);
+  const append = (m: string, d?: string) => setLog((l) => [d ? `${m}: ${d}` : m, ...l]);
+
+  const install = useDeviceInstallRelay({ apiUrl, token, log: append });
+  const build = useDeviceBuild({ apiUrl, token, signingAssets });
+
+  async function prepare() {
+    if (!certificateFile || !profileFile) return;
+    setSigningAssets(
+      await importSigningAssetsFromFiles({
+        certificateFile,
+        provisioningProfileFile: profileFile,
+        certificatePassword,
+        bundleId,
+        deviceUDID: install.device?.hello.serialNumber,
+        signingMode: 'development',
+      }),
+    );
+  }
+
+  return (
+    <div>
+      {(install.error || build.error) && <pre>{install.error ?? build.error}</pre>}
+
+      <button disabled={!!install.busyAction} onClick={() => void install.requestUSBAccess()}>
+        Select iPhone
+      </button>
+      <button disabled={!install.canPair} onClick={() => void install.pairBrowser()}>
+        Pair
+      </button>
+
+      <input type="file" accept=".p12" onChange={(e) => setCertificateFile(e.currentTarget.files?.[0])} />
+      <input
+        type="file"
+        accept=".mobileprovision"
+        onChange={(e) => setProfileFile(e.currentTarget.files?.[0])}
+      />
+      <input
+        type="password"
+        value={certificatePassword}
+        onChange={(e) => setCertificatePassword(e.currentTarget.value)}
+      />
+      <button disabled={!certificateFile || !profileFile} onClick={() => void prepare()}>
+        Prepare signing assets
+      </button>
+
+      <button disabled={!signingAssets || build.status === 'running'} onClick={() => void build.startBuild()}>
+        Start signed build ({build.status})
+      </button>
+
+      <button
+        disabled={!install.canInstall || build.status !== 'succeeded'}
+        onClick={() => void install.startInstallation()}
+      >
+        Install
+      </button>
+
+      <pre>{log.join('\n')}</pre>
+    </div>
+  );
+}
+```
+
+A more complete, styled reference (with the Apple Developer flow, a status
+stepper, and error handling) lives in
+[`src/device-install/demo`](./demo) in this package — see
+[`demo.tsx`](./demo/demo.tsx) for the full source.
+
+## Run the demo
+
+The demo is a standalone Vite page you can run against any Xcode build sandbox:
+
+```bash
+cd packages/ui
+npm install
+npx vite src/device-install/demo
+```
+
+Open the printed `https://localhost` URL in Chrome or Edge, paste your sandbox's
+`apiUrl` and `token`, then walk through pair → sign → build → install. The page
+exercises the same hooks and helpers documented above, so it doubles as a
+copy-paste reference for your own integration.
+
+## Add a device to a profile
+
+Provisioning profiles can't be edited in place. To authorize a new iPhone,
+**register the UDID, then regenerate the profile** with it included:
+
+1. `registerAppleDevice({ deviceUDID })` — add the UDID to the team.
+2. `createAppleProfile({ ..., deviceIds: [...existing, newDeviceId] })` — mint a
+   fresh profile (unique `name`).
+3. `downloadAppleProfile(...)` — fetch the new bytes.
+
+This needs an Apple Developer session. A manually uploaded `.mobileprovision`
+that's missing the device can't be amended locally — regenerate it through the
+Apple flow.
+
+## Storage and security
+
+- **Pair records** and **signing assets** (`.p12`, `.mobileprovision`, and the
+  `.p12` password when given) live in the browser's IndexedDB, written only when
+  you call the storage helpers. They stay on the device unless your app moves
+  them.
+- The **Apple ID password never reaches Limrun** — only SRP proof material does.
+- The sandbox `token` is instance-scoped; the Apple session is held in the
+  browser. Treat any `.p12` and password your app handles as secrets, and serve
+  the UI over HTTPS in production.
+
+## Troubleshooting
+
+| Symptom                                                                                          | Cause and fix                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WebUSB is not available`                                                                        | Use Chrome/Edge on HTTPS or `localhost`. Safari/Firefox are unsupported.                                                                                                                                     |
+| `Unable to claim interface` / "operation in progress"                                            | Unplug/replug the iPhone, unlock it, close other WebUSB tabs, retry. Make sure you're on a current `@limrun/ui`.                                                                                             |
+| First transfer fails with _"endpoint is not part of a claimed and selected alternate interface"_ | Update `@limrun/ui` — recent versions explicitly select the usbmux alternate (incl. alt 0).                                                                                                                  |
+| Pairing seems to hang                                                                            | The user must unlock the iPhone and tap **Trust**; the first attempt can fail if the prompt isn't accepted in time. Retry.                                                                                   |
+| `no synced folder found; call /sync first`                                                       | Sync your project into the sandbox first (`lim xcode build .` / `lim xcode sync .`).                                                                                                                         |
+| Install fails, log shows `ApplicationVerificationFailed`                                         | Signed with a **revoked/invalid cert**, or the **device isn't in the profile**, or the **bundle ID isn't covered**. `zsign` doesn't rewrite the bundle ID — it must match (or be wildcarded by) the profile. |
+| `no current certificates matching the provided certificate IDs`                                  | You passed a `certRequestId`, or the cert was revoked. Resolve the canonical `certificateId` via `listAppleCertificates`.                                                                                    |
+| `You already have a current Development certificate…`                                            | Apple's cert cap. Reuse a stored cert, upload a `.p12`, or revoke one at developer.apple.com.                                                                                                                |
+| `Multiple profiles found with the name '…'`                                                      | Give created profiles a unique name.                                                                                                                                                                         |
+| Apple flow does nothing after sign-in                                                            | Resolve the team id across `teamId`/`providerId`/`publicProviderId`.                                                                                                                                         |
+
+## Next steps
+
+Provision an Xcode sandbox, sync source, and produce signed IPAs. Drive a simulator for the same app: taps, screenshots, logs, recordings. Build every PR and post a live preview link from a GitHub workflow.