@limrun/ui 0.14.0-rc.2 → 0.14.0-rc.4

package/src/apple-credentials/index.ts

@@ -0,0 +1,241 @@
+/**
+ * Headless helpers that turn an authenticated Apple relay session into
+ * signing credentials persisted in a SigningSecretStore. The Apple relay
+ * only proxies: certificate and profile bytes always land in the browser
+ * first, and the browser writes them into the configured store (Limrun's
+ * org secret store by default, or a customer-provided one).
+ */
+import {
+  createAppleCertificate,
+  downloadAppleCertificate,
+  downloadAppleProfile,
+  exportAppleCertificateP12,
+  generateAppleSigningKeyAndCSR,
+  listAppleCertificates,
+  listAppleProfiles,
+} from '../app-store-relay';
+import type { AppleRelayWebSocketClient } from '../core/device-install/apple';
+import {
+  normalizeCertificateSerial,
+  parseProvisioningProfileBase64,
+} from '../core/device-install/storage/browser-storage';
+import {
+  APPLE_CERTIFICATE_SECRET_TYPE,
+  putAppleCertificateSecret,
+  putAppleProvisioningProfileSecret,
+  type AppleCertificateSecretData,
+  type AppleCertificateType,
+  type SigningSecret,
+  type SigningSecretStore,
+} from '../core/device-install/storage/secret-store';
+
+export {
+  APPLE_CERTIFICATE_SECRET_TYPE,
+  APPLE_PROVISIONING_PROFILE_SECRET_TYPE,
+  createBrowserSecretStore,
+  createLimrunSecretStore,
+  putAppleCertificateSecret,
+  putAppleProvisioningProfileSecret,
+  type AppleCertificateSecretData,
+  type AppleCertificateType,
+  type AppleProvisioningProfileSecretData,
+  type LimrunSecretStoreOptions,
+  type SigningSecret,
+  type SigningSecretData,
+  type SigningSecretMetadata,
+  type SigningSecretStore,
+  type SigningSecretType,
+} from '../core/device-install/storage/secret-store';
+export { normalizeCertificateSerial } from '../core/device-install/storage/browser-storage';
+
+/**
+ * Conventional secret name of a team's certificate bundle. One bundle per
+ * team and Apple certificate type; the type is in the name so development
+ * and distribution material never collide.
+ */
+export function appleCertificateSecretName(teamId: string, certificateType: AppleCertificateType) {
+  return `${teamId}/${certificateType}`;
+}
+
+export type EnsureAppleCertificateInput = {
+  relay: AppleRelayWebSocketClient;
+  teamId: string;
+  secretStore: SigningSecretStore;
+  /** Common name used when minting a new certificate. */
+  commonName?: string;
+  log?: (message: string, detail?: string) => void;
+};
+
+export type EnsureAppleCertificateResult = {
+  secret: SigningSecret;
+  certificateId: string;
+  /** True when a new certificate was minted instead of reusing the stored one. */
+  created: boolean;
+};
+
+/**
+ * Returns a usable development certificate secret for the team, reusing the
+ * stored one when its certificate is still on the team and minting a new
+ * one otherwise. Apple caps development certificates at 2 and never returns
+ * private keys, so reuse of the stored p12 is strongly preferred.
+ *
+ * Durability of the stored material is the secret store's concern:
+ * implementors who want retries or fallbacks build them into their
+ * SigningSecretStore.
+ */
+export async function ensureAppleCertificateSecret({
+  relay,
+  teamId,
+  secretStore,
+  commonName,
+  log = () => {},
+}: EnsureAppleCertificateInput): Promise<EnsureAppleCertificateResult> {
+  // The browser flow mints via the portal's development kind, which is
+  // the DEVELOPMENT certificate type in Apple's App Store Connect enum.
+  const certificateType: AppleCertificateType = 'DEVELOPMENT';
+  const secretName = appleCertificateSecretName(teamId, certificateType);
+  const current = await listAppleCertificates({ relay, teamId, certificateKind: 'development' });
+  const findOnTeam = (certificateId: string | undefined) =>
+    certificateId === undefined ? undefined : (
+      current.find(
+        (item) =>
+          stringField(item, 'certificateId') === certificateId ||
+          stringField(item, 'certRequestId') === certificateId,
+      )
+    );
+
+  const stored = await secretStore.get(APPLE_CERTIFICATE_SECRET_TYPE, secretName);
+  const storedCertificateId = stringField(stored?.data, 'certificateID');
+  if (stored && storedCertificateId && stored.data.certificateP12Base64) {
+    // The stored value may be a certRequestId; resolve the canonical
+    // certificateId the profile API expects. If the cert is no longer on
+    // the team (revoked), fall through and mint a new one.
+    const matched = findOnTeam(storedCertificateId);
+    if (matched) {
+      const certificateId = stringField(matched, 'certificateId') ?? storedCertificateId;
+      log('Reusing stored Apple certificate', certificateId);
+      return { secret: stored, certificateId, created: false };
+    }
+    log('Stored certificate is no longer on the team', 'Minting a new one.');
+  }
+
+  // The private key is generated and kept in this browser; Apple only ever
+  // sees the CSR. Without this key the downloaded cert cannot sign anything.
+  const key = await generateAppleSigningKeyAndCSR({ commonName: commonName ?? `Limrun ${teamId}` });
+  const certificate = await createAppleCertificate({
+    relay,
+    teamId,
+    certificateKind: 'development',
+    csrPEM: key.csrPEM,
+  });
+  const certificateId =
+    stringField(certificate, 'certificateId') ?? stringField(certificate, 'certRequestId');
+  if (!certificateId) {
+    throw new Error('Apple certificate creation did not return a certificate ID.');
+  }
+  const downloaded = await downloadAppleCertificate({
+    relay,
+    teamId,
+    certificateKind: 'development',
+    certificateId,
+  });
+  if (!downloaded.rawBodyBase64) {
+    throw new Error('Apple certificate download returned no bytes.');
+  }
+  const data: AppleCertificateSecretData = {
+    certificateP12Base64: exportAppleCertificateP12({
+      privateKeyPKCS8Base64: key.privateKeyPKCS8Base64,
+      certificateBase64: downloaded.rawBodyBase64,
+      password: '',
+      friendlyName: `Apple Development ${teamId}`,
+    }),
+    certificateType,
+    teamID: teamId,
+    certificateID: certificateId,
+    // Normalized so it equals the serials profiles reference.
+    serialNumber: normalizeCertificateSerial(stringField(certificate, 'serialNum')),
+    expirationDate: stringField(certificate, 'expirationDateString'),
+  };
+
+  let secret: SigningSecret;
+  try {
+    secret = await putAppleCertificateSecret(secretStore, secretName, data);
+  } catch (error) {
+    // The key existed only in this browser's memory; once this throw
+    // unwinds it is gone, and the portal certificate is unusable.
+    throw new Error(
+      `Certificate ${certificateId} was created on the Apple Developer portal but saving its private ` +
+        `key to the secret store failed: ${errorText(error)}. The key cannot be recovered; revoke ` +
+        `certificate ${certificateId} at developer.apple.com before retrying, or the retry will mint ` +
+        `another certificate against Apple's limit.`,
+    );
+  }
+  log('Apple certificate stored', certificateId);
+  return { secret, certificateId, created: true };
+}
+
+function errorText(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export type SaveAppleProfileInput = {
+  relay: AppleRelayWebSocketClient;
+  teamId: string;
+  profileId: string;
+  secretStore: SigningSecretStore;
+  log?: (message: string, detail?: string) => void;
+};
+
+/**
+ * Downloads the provisioning profile and stores it as an
+ * appleProvisioningProfile secret named `${teamId}/${uuid}`. The UUID is
+ * unique per profile, so a team can hold many profiles for the same
+ * bundle ID and certificate set; the reference fields (certificate
+ * serials, bundle IDs, device IDs parsed out of the profile) are what
+ * consumers filter on.
+ */
+export async function saveAppleProfileSecret({
+  relay,
+  teamId,
+  profileId,
+  secretStore,
+  log = () => {},
+}: SaveAppleProfileInput): Promise<SigningSecret> {
+  const downloaded = await downloadAppleProfile({ relay, teamId, profileId });
+  const profileBase64 = downloaded.rawBodyBase64;
+  if (!profileBase64) {
+    throw new Error('Apple provisioning profile download returned no bytes.');
+  }
+  const info = parseProvisioningProfileBase64(profileBase64);
+  const name = `${teamId}/${info.uuid ?? profileId}`;
+  const secret = await putAppleProvisioningProfileSecret(secretStore, name, {
+    provisioningProfileBase64: profileBase64,
+    certificateSerialNumbers: info.certificateSerialNumbers.join(','),
+    bundleIDs: info.bundleID,
+    deviceIDs: info.provisionedDevices.join(','),
+    teamID: info.teamID ?? teamId,
+    profileName: info.name,
+    uuid: info.uuid,
+    expirationDate: info.expirationDate,
+  });
+  log('Apple provisioning profile stored', name);
+  return secret;
+}
+
+export type ListTeamProfilesInput = {
+  relay: AppleRelayWebSocketClient;
+  teamId: string;
+};
+
+/** Lists the team's development provisioning profiles from the portal. */
+export async function listTeamAppleProfiles({ relay, teamId }: ListTeamProfilesInput) {
+  return listAppleProfiles({ relay, teamId, profileKind: 'development' });
+}
+
+/** Read a string-ish value from a loosely typed portal record. */
+export function stringField(record: Record<string, unknown> | undefined, key: string) {
+  const value = record?.[key];
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return undefined;
+}

package/src/core/device-install/apple/client.ts

@@ -99,12 +99,7 @@ export async function startBrowserOwnedAppleIDLogin({
       finishTwoFactor: async (code) => {
         const response =
           twoFactorMethod.type === 'phone' ?
-            await proxyPhoneTwoFactorCode(
-              relay,
-              twoFactorMethod.phoneNumberId,
-              code,
-              twoFactorMethod.mode,
-            )
+            await proxyPhoneTwoFactorCode(relay, twoFactorMethod.phoneNumberId, code, twoFactorMethod.mode)
           : await proxyTwoFactorCode(relay, code);
         if (response.status < 200 || response.status >= 300) {
           throw new Error(

package/src/core/device-install/apple/relay.ts

@@ -104,10 +104,7 @@ export async function openAppleRelayWebSocket(apiUrl: string, token?: string, or
   return client;
 }
 
-export async function proxySrpInit(
-  relay: AppleRelayWebSocketClient,
-  payload: AppleSRPInitRequest,
-) {
+export async function proxySrpInit(relay: AppleRelayWebSocketClient, payload: AppleSRPInitRequest) {
   return relay.request<AppleSRPInitResponse>('srpInit', payload);
 }
 

package/src/core/device-install/operations/operations.ts

@@ -4,6 +4,7 @@ import type { DeviceHello, DeviceInstallLog, PairRecordPayload } from '../types'
 import { RelayClient } from './relay-client';
 import { closeUsbmuxSession, createUsbmuxSession, type UsbmuxSession } from './usbmux';
 import { claimUsbmux, findUsbmuxCandidates, requestAppleDevice, type UsbmuxCandidate } from './webusb';
+import { errorMessage } from '../../errors';
 
 export type DeviceRelayTarget = {
   device: USBDevice;
@@ -46,7 +47,13 @@ export async function requestUSBAccess({ log }: RequestUSBAccessOptions) {
   return target;
 }
 
-export async function startPairingRelay({ registryApiUrl, token, organizationId, log, target }: StartPairingRelayOptions) {
+export async function startPairingRelay({
+  registryApiUrl,
+  token,
+  organizationId,
+  log,
+  target,
+}: StartPairingRelayOptions) {
   const deviceRelayUrl = deviceRelayWebSocketUrl(registryApiUrl, token, organizationId);
   let relay: RelayClient | undefined;
   try {
@@ -204,10 +211,6 @@ export function deviceRelayWebSocketUrl(registryApiUrl: string, token?: string,
   return url.toString();
 }
 
-function errorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 async function resetUSBDevice(target: DeviceRelayTarget) {
   if (target.claimedInterfaceNumber !== undefined) {
     try {

package/src/core/device-install/storage/browser-storage.test.ts

@@ -0,0 +1,65 @@
+import forge from 'node-forge';
+import { describe, expect, test } from 'vitest';
+import { normalizeCertificateSerial, parseProvisioningProfileBase64 } from './browser-storage';
+
+function selfSignedCertificateBase64(serialNumber: string) {
+  const keys = forge.pki.rsa.generateKeyPair(1024);
+  const cert = forge.pki.createCertificate();
+  cert.publicKey = keys.publicKey;
+  cert.serialNumber = serialNumber;
+  cert.validity.notBefore = new Date();
+  cert.validity.notAfter = new Date(Date.now() + 24 * 60 * 60 * 1000);
+  const attrs = [{ name: 'commonName', value: 'Apple Development Test' }];
+  cert.setSubject(attrs);
+  cert.setIssuer(attrs);
+  cert.sign(keys.privateKey);
+  return forge.util.encode64(forge.asn1.toDer(forge.pki.certificateToAsn1(cert)).getBytes());
+}
+
+function profileBase64(certificatesBase64: string[]) {
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0">
+<dict>
+  <key>Name</key><string>Limrun Dev</string>
+  <key>UUID</key><string>11111111-2222-3333-4444-555555555555</string>
+  <key>TeamIdentifier</key><array><string>TEAM123</string></array>
+  <key>ProvisionedDevices</key><array><string>00008030-000A</string></array>
+  <key>DeveloperCertificates</key>
+  <array>${certificatesBase64.map((c) => `<data>${c}</data>`).join('')}</array>
+  <key>Entitlements</key>
+  <dict>
+    <key>application-identifier</key><string>TEAM123.com.example.app</string>
+    <key>com.apple.developer.team-identifier</key><string>TEAM123</string>
+  </dict>
+</dict>
+</plist>`;
+  return btoa(xml);
+}
+
+describe('parseProvisioningProfileBase64', () => {
+  test('extracts embedded certificate serial numbers in normalized form', () => {
+    const parsed = parseProvisioningProfileBase64(
+      profileBase64([selfSignedCertificateBase64('00ab12cd'), selfSignedCertificateBase64('7f')]),
+    );
+    expect(parsed.certificateSerialNumbers).toEqual(['AB12CD', '7F']);
+    expect(parsed.bundleID).toBe('com.example.app');
+    expect(parsed.teamID).toBe('TEAM123');
+    expect(parsed.provisionedDevices).toEqual(['00008030-000A']);
+  });
+
+  test('skips unparseable certificates instead of failing the profile', () => {
+    const parsed = parseProvisioningProfileBase64(
+      profileBase64([btoa('not a certificate'), selfSignedCertificateBase64('1a')]),
+    );
+    expect(parsed.certificateSerialNumbers).toEqual(['1A']);
+  });
+});
+
+describe('normalizeCertificateSerial', () => {
+  test('uppercases and strips leading zeros', () => {
+    expect(normalizeCertificateSerial('00ab12')).toBe('AB12');
+    expect(normalizeCertificateSerial('AB12')).toBe('AB12');
+    expect(normalizeCertificateSerial('')).toBeUndefined();
+    expect(normalizeCertificateSerial(undefined)).toBeUndefined();
+  });
+});

package/src/core/device-install/storage/browser-storage.ts

@@ -1,3 +1,4 @@
+import forge from 'node-forge';
 import type {
   DeviceInstallSigningMode,
   ProvisioningProfileInfo,
@@ -198,11 +199,43 @@ export function parseProvisioningProfileBytes(bytes: Uint8Array) {
     applicationIdentifier,
     bundleID,
     provisionedDevices: stringArrayValue(value.ProvisionedDevices),
+    certificateSerialNumbers: certificateSerialNumbers(stringArrayValue(value.DeveloperCertificates)),
     getTaskAllow: booleanValue(entitlements['get-task-allow']),
     expirationDate: stringValue(value.ExpirationDate),
   } satisfies ProvisioningProfileInfo;
 }
 
+/**
+ * Normalizes a certificate serial number for comparison: uppercase hex
+ * without leading zeros, the format Apple's portal reports in serialNum.
+ */
+export function normalizeCertificateSerial(serial?: string) {
+  const normalized = (serial ?? '').replace(/^0+/, '').toUpperCase();
+  return normalized || undefined;
+}
+
+/**
+ * Reads the serial numbers of the DER certificates embedded in a profile's
+ * DeveloperCertificates array. Unparseable entries are skipped: a profile
+ * with an exotic certificate should degrade to weaker filtering, not fail
+ * the whole parse.
+ */
+function certificateSerialNumbers(developerCertificatesBase64: string[]) {
+  const serials: string[] = [];
+  for (const entry of developerCertificatesBase64) {
+    try {
+      // Plist <data> payloads wrap base64 across lines; atob rejects whitespace.
+      const der = atob(entry.replace(/\s+/g, ''));
+      const certificate = forge.pki.certificateFromAsn1(forge.asn1.fromDer(forge.util.createBuffer(der)));
+      const serial = normalizeCertificateSerial(certificate.serialNumber);
+      if (serial && !serials.includes(serial)) serials.push(serial);
+    } catch {
+      // Skip certificates forge cannot parse.
+    }
+  }
+  return serials;
+}
+
 async function getSigningAssetsByID(id?: string) {
   if (!id) return undefined;
   const db = await openDB(SIGNING_DB_NAME, SIGNING_DB_VERSION, SIGNING_STORE_NAME, 'id');

package/src/core/device-install/storage/index.ts

@@ -1 +1,2 @@
 export * from './browser-storage';
+export * from './secret-store';