@particle/esim-tooling 1.0.0

package/src/lpa.ts

@@ -0,0 +1,346 @@
+import { Es10Error, Es9PlusError, EsimError } from './errors.js';
+import {
+  EnableProfileResult,
+  DisableProfileResult,
+  DeleteProfileResult,
+  CancelSessionReason,
+  BppInstallErrorCode,
+  type ServerAdapter,
+  type Profile,
+  type Notification,
+  type NotificationWithResult,
+  type SendResult,
+  type ProcessNotificationsOptions,
+  type ProcessNotificationsResult,
+  type DownloadResult,
+  type DownloadProgress,
+  type InstallProfileOptions,
+  type EsimLpaOptions,
+} from './types.js';
+import { ApduTransport } from './apdu.js';
+import {
+  encodeGetEidRequest,
+  decodeGetEidResponse,
+  encodeGetProfilesInfoRequest,
+  decodeGetProfilesInfoResponse,
+  encodeEnableProfileRequest,
+  decodeEnableProfileResponse,
+  encodeDisableProfileRequest,
+  decodeDisableProfileResponse,
+  encodeDeleteProfileRequest,
+  decodeDeleteProfileResponse,
+} from './es10/es10c.js';
+import {
+  encodeGetEuiccChallengeRequest,
+  decodeGetEuiccChallengeResponse,
+  encodeGetEuiccInfo1Request,
+  encodeAuthenticateServerRequest,
+  decodeAuthenticateServerResponse,
+  encodePrepareDownloadRequest,
+  decodePrepareDownloadResponse,
+  hashConfirmationCode,
+  encodeCancelSessionRequest,
+} from './es10/es10b.js';
+import {
+  encodeRetrieveNotificationsListRequest,
+  decodeRetrieveNotificationsListFull,
+  decodeBppInstallationResult,
+  encodeRemoveNotificationRequest,
+} from './es10/es10b-notifications.js';
+import { parseActivationCode } from './activation-code.js';
+import { Es9PlusClient } from './es9plus.js';
+
+export class EsimLpa {
+  private apdu: ApduTransport;
+  private es9plus: Es9PlusClient;
+
+  constructor(options: EsimLpaOptions) {
+    this.apdu = new ApduTransport(options.device);
+    this.es9plus = new Es9PlusClient(options.server);
+  }
+
+  async getEid(): Promise<string> {
+    try {
+      const request = encodeGetEidRequest();
+      const response = await this.apdu.sendCommand(request);
+      return decodeGetEidResponse(response);
+    } finally {
+      await this.apdu.close();
+    }
+  }
+
+  async listProfiles(): Promise<Profile[]> {
+    try {
+      const request = encodeGetProfilesInfoRequest();
+      const response = await this.apdu.sendCommand(request);
+      return decodeGetProfilesInfoResponse(response);
+    } finally {
+      await this.apdu.close();
+    }
+  }
+
+  async enableProfile(iccid: string, refreshFlag = false): Promise<void> {
+    try {
+      const request = encodeEnableProfileRequest(iccid, refreshFlag);
+      const response = await this.apdu.sendCommand(request);
+      const result = decodeEnableProfileResponse(response);
+      if (result !== EnableProfileResult.Ok) {
+        throw new Es10Error(result, `enableProfile failed: ${EnableProfileResult[result] ?? result}`);
+      }
+    } finally {
+      await this.apdu.close();
+    }
+  }
+
+  async disableProfile(iccid: string, refreshFlag = false): Promise<void> {
+    try {
+      const request = encodeDisableProfileRequest(iccid, refreshFlag);
+      const response = await this.apdu.sendCommand(request);
+      const result = decodeDisableProfileResponse(response);
+      if (result !== DisableProfileResult.Ok) {
+        throw new Es10Error(result, `disableProfile failed: ${DisableProfileResult[result] ?? result}`);
+      }
+    } finally {
+      await this.apdu.close();
+    }
+  }
+
+  async deleteProfile(iccid: string): Promise<void> {
+    try {
+      const request = encodeDeleteProfileRequest(iccid);
+      const response = await this.apdu.sendCommand(request);
+      const result = decodeDeleteProfileResponse(response);
+      if (result !== DeleteProfileResult.Ok) {
+        throw new Es10Error(result, `deleteProfile failed: ${DeleteProfileResult[result] ?? result}`);
+      }
+    } finally {
+      await this.apdu.close();
+    }
+  }
+
+  async installProfile(options: InstallProfileOptions): Promise<DownloadResult> {
+    const progress = (step: DownloadProgress['step'], detail?: string) => {
+      options.onProgress?.({ step, detail });
+    };
+
+    let transactionId: string | undefined;
+    let smdpAddress: string | undefined;
+
+    try {
+      // Step 1: Parse activation code
+      progress('parseActivationCode');
+      const ac = parseActivationCode(options.activationCode);
+      smdpAddress = ac.smdpAddress;
+
+      // Step 2: Get eUICC challenge
+      progress('getEuiccChallenge');
+      const challengeReq = encodeGetEuiccChallengeRequest();
+      const challengeResp = await this.apdu.sendCommand(challengeReq);
+      const euiccChallenge = decodeGetEuiccChallengeResponse(challengeResp);
+
+      // Step 3: Get eUICC info
+      progress('getEuiccInfo');
+      const info1Req = encodeGetEuiccInfo1Request();
+      const euiccInfo1 = await this.apdu.sendCommand(info1Req);
+
+      // Step 4: Initiate authentication with SM-DP+
+      progress('initiateAuth');
+      const initAuthResp = await this.es9plus.initiateAuthentication(smdpAddress, {
+        euiccChallenge,
+        euiccInfo1,
+      });
+      transactionId = initAuthResp.transactionId;
+
+      // Step 5: Authenticate server on eUICC
+      progress('authenticateServer');
+      const authServerReq = encodeAuthenticateServerRequest({
+        serverSigned1: initAuthResp.serverSigned1,
+        serverSignature1: initAuthResp.serverSignature1,
+        euiccCiPKIdToBeUsed: initAuthResp.euiccCiPKIdToBeUsed,
+        serverCertificate: initAuthResp.serverCertificate,
+        matchingId: ac.matchingId || undefined,
+      });
+      const authServerResp = await this.apdu.sendCommand(authServerReq);
+      const authServerDecoded = decodeAuthenticateServerResponse(authServerResp);
+
+      // Step 6: Authenticate client on SM-DP+
+      progress('authenticateClient');
+      const authClientResp = await this.es9plus.authenticateClient(smdpAddress, {
+        transactionId,
+        authenticateServerResponse: authServerDecoded.raw,
+      });
+
+      // Step 7: Prepare download on eUICC
+      progress('prepareDownload');
+      let hashCc: Uint8Array | undefined;
+      if (options.confirmationCode) {
+        hashCc = await hashConfirmationCode(options.confirmationCode, transactionId);
+      }
+      const prepDlReq = encodePrepareDownloadRequest({
+        smdpSigned2: authClientResp.smdpSigned2,
+        smdpSignature2: authClientResp.smdpSignature2,
+        smdpCertificate: authClientResp.smdpCertificate,
+        hashCc,
+      });
+      const prepDlResp = await this.apdu.sendCommand(prepDlReq);
+      const prepDlDecoded = decodePrepareDownloadResponse(prepDlResp);
+
+      // Step 8: Get bound profile package from SM-DP+
+      progress('getBoundProfilePackage');
+      const bppResp = await this.es9plus.getBoundProfilePackage(smdpAddress, {
+        transactionId,
+        prepareDownloadResponse: prepDlDecoded.raw,
+      });
+
+      // Step 9: Load bound profile package on eUICC
+      progress('loadProfile');
+      const bppResultRaw = await this.apdu.loadBoundProfilePackage(bppResp.boundProfilePackage);
+
+      // Parse ProfileInstallationResult from eUICC (if returned)
+      let installResult;
+      if (bppResultRaw && bppResultRaw.length > 0) {
+        try {
+          installResult = decodeBppInstallationResult(bppResultRaw);
+          if (!installResult.success) {
+            // Return structured failure instead of throwing
+            const errorName = BppInstallErrorCode[installResult.errorReasonCode ?? -1] ?? 'Unknown';
+            return {
+              success: false,
+              error: `Profile installation failed: ${errorName}`,
+              errorSubjectCode: installResult.errorSubjectCode,
+              errorReasonCode: installResult.errorReasonCode,
+            };
+          }
+        } catch {
+          // If parsing fails but no error was thrown during BPP loading, continue
+          // The eUICC may not return a result in all cases
+        }
+      }
+
+      // Step 10: Complete
+      progress('complete');
+      // Prefer ICCID from eUICC result (confirms actual installation), fallback to ES9+ metadata
+      const iccid = installResult?.iccid ?? authClientResp.profileMetadata?.iccid;
+      return {
+        success: true,
+        iccid,
+        profileMetadata: authClientResp.profileMetadata
+          ? {
+              serviceProviderName: authClientResp.profileMetadata.serviceProviderName,
+              profileName: authClientResp.profileMetadata.profileName,
+            }
+          : undefined,
+      };
+    } catch (error) {
+      // Attempt cancel session on failure (best-effort)
+      if (transactionId && smdpAddress) {
+        await this.cancelSessionBestEffort(smdpAddress, transactionId, error);
+      }
+
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    } finally {
+      await this.apdu.close();
+    }
+  }
+
+  async processNotifications(options?: ProcessNotificationsOptions): Promise<ProcessNotificationsResult> {
+    const listOnly = options?.listOnly ?? false;
+    const forceRemove = options?.forceRemove ?? false;
+
+    try {
+      // Single eUICC call: retrieve all notifications with metadata and raw bytes
+      const request = encodeRetrieveNotificationsListRequest();
+      const response = await this.apdu.sendCommand(request);
+      const notifications = decodeRetrieveNotificationsListFull(response);
+
+      // Sort by seqNumber (eUICC may return in arbitrary order)
+      notifications.sort((a, b) => a.seqNumber - b.seqNumber);
+
+      // If listOnly, just return notifications with sendResult: null
+      if (listOnly) {
+        const results: NotificationWithResult[] = notifications.map((n) => ({
+          seqNumber: n.seqNumber,
+          operation: n.operation,
+          notificationAddress: n.notificationAddress,
+          iccid: n.iccid,
+          success: n.success,
+          errorSubjectCode: n.errorSubjectCode,
+          errorReasonCode: n.errorReasonCode,
+          sendResult: null,
+        }));
+        return { notifications: results };
+      }
+
+      const results: NotificationWithResult[] = [];
+      let sent = 0;
+      let failed = 0;
+
+      // Process each notification - raw bytes already available from initial call
+      for (const notification of notifications) {
+        const sendResult: SendResult = {
+          sent: false,
+          removed: false,
+        };
+
+        try {
+          // Send raw PendingNotification bytes to SM-DP+
+          await this.es9plus.handleNotification(notification.notificationAddress, notification.raw);
+          sendResult.sent = true;
+          sent++;
+        } catch (error) {
+          sendResult.error = error instanceof Error ? error.message : String(error);
+          failed++;
+        }
+
+        // Remove from eUICC if successfully sent, or if forceRemove is enabled
+        if (sendResult.sent || forceRemove) {
+          try {
+            const removeReq = encodeRemoveNotificationRequest(notification.seqNumber);
+            await this.apdu.sendCommand(removeReq);
+            sendResult.removed = true;
+          } catch {
+            // Best-effort removal
+          }
+        }
+
+        results.push({
+          seqNumber: notification.seqNumber,
+          operation: notification.operation,
+          notificationAddress: notification.notificationAddress,
+          iccid: notification.iccid,
+          success: notification.success,
+          errorSubjectCode: notification.errorSubjectCode,
+          errorReasonCode: notification.errorReasonCode,
+          sendResult,
+        });
+      }
+
+      return { notifications: results, sent, failed };
+    } finally {
+      await this.apdu.close();
+    }
+  }
+
+  private async cancelSessionBestEffort(smdpAddress: string, transactionId: string, _error: unknown): Promise<void> {
+    try {
+      const reason = CancelSessionReason.LoadBppExecutionError;
+      const txIdBytes = hexToBytes(transactionId);
+      const cancelReq = encodeCancelSessionRequest(txIdBytes, reason);
+      const cancelResp = await this.apdu.sendCommand(cancelReq);
+      await this.es9plus.cancelSession(smdpAddress, transactionId, cancelResp);
+    } catch {
+      // Best-effort — ignore cancel failures
+    }
+  }
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}

package/src/tlv.ts

@@ -0,0 +1,137 @@
+import { TlvError } from './errors.js';
+
+export interface TlvNode {
+  tag: number;
+  value: Uint8Array;
+  children?: TlvNode[];
+  raw?: Uint8Array;
+}
+
+// Tags known to be constructed (have children)
+const CONSTRUCTED_TAGS = new Set([
+  0xa0, 0xa1, 0xa2, 0xa3, 0xe3,
+  0xbf20, 0xbf21, 0xbf22, 0xbf28, 0xbf29, 0xbf2b, 0xbf2d, 0xbf2e, 0xbf2f,
+  0xbf30, 0xbf31, 0xbf32, 0xbf33, 0xbf34, 0xbf36, 0xbf38, 0xbf3e, 0xbf41, 0xbf43,
+]);
+
+function isConstructed(tag: number): boolean {
+  if (CONSTRUCTED_TAGS.has(tag)) return true;
+  // Check constructed bit (bit 5 of the first byte)
+  const firstByte = tag > 0xff ? (tag >> 8) & 0xff : tag;
+  return (firstByte & 0x20) !== 0;
+}
+
+function readTag(data: Uint8Array, offset: number): [number, number] {
+  if (offset >= data.length) throw new TlvError('Unexpected end of data reading tag');
+  let tag = data[offset++];
+  if ((tag & 0x1f) === 0x1f) {
+    // Multi-byte tag
+    if (offset >= data.length) throw new TlvError('Unexpected end of data reading multi-byte tag');
+    let next = data[offset++];
+    tag = (tag << 8) | next;
+    if (next & 0x80) {
+      // Three-byte tag
+      if (offset >= data.length) throw new TlvError('Unexpected end of data reading 3-byte tag');
+      next = data[offset++];
+      tag = (tag << 8) | next;
+    }
+  }
+  return [tag, offset];
+}
+
+function readLength(data: Uint8Array, offset: number): [number, number] {
+  if (offset >= data.length) throw new TlvError('Unexpected end of data reading length');
+  const first = data[offset++];
+  if (first < 0x80) return [first, offset];
+  const numBytes = first & 0x7f;
+  if (numBytes === 0) throw new TlvError('Indefinite length not supported');
+  if (numBytes > 3) throw new TlvError(`Length field too large: ${numBytes} bytes`);
+  if (offset + numBytes > data.length) throw new TlvError('Unexpected end of data reading length');
+  let length = 0;
+  for (let i = 0; i < numBytes; i++) {
+    length = (length << 8) | data[offset++];
+  }
+  return [length, offset];
+}
+
+function encodeTag(tag: number): Uint8Array {
+  if (tag <= 0xff) return new Uint8Array([tag]);
+  if (tag <= 0xffff) return new Uint8Array([(tag >> 8) & 0xff, tag & 0xff]);
+  return new Uint8Array([(tag >> 16) & 0xff, (tag >> 8) & 0xff, tag & 0xff]);
+}
+
+function encodeLength(length: number): Uint8Array {
+  if (length < 0x80) return new Uint8Array([length]);
+  if (length <= 0xff) return new Uint8Array([0x81, length]);
+  if (length <= 0xffff) return new Uint8Array([0x82, (length >> 8) & 0xff, length & 0xff]);
+  return new Uint8Array([0x83, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff]);
+}
+
+export function tlvEncode(tag: number, value: Uint8Array): Uint8Array {
+  const tagBytes = encodeTag(tag);
+  const lengthBytes = encodeLength(value.length);
+  return tlvConcat(tagBytes, lengthBytes, value);
+}
+
+export function tlvDecode(data: Uint8Array, offset = 0): TlvNode {
+  const rawStart = offset;
+  const [tag, afterTag] = readTag(data, offset);
+  const [length, afterLength] = readLength(data, afterTag);
+  if (afterLength + length > data.length) {
+    throw new TlvError(`TLV length ${length} exceeds available data (${data.length - afterLength} bytes)`);
+  }
+  const value = data.slice(afterLength, afterLength + length);
+  const raw = data.slice(rawStart, afterLength + length);
+
+  let children: TlvNode[] | undefined;
+  if (isConstructed(tag) && length > 0) {
+    children = [];
+    let childOffset = 0;
+    while (childOffset < value.length) {
+      const child = tlvDecode(value, childOffset);
+      children.push(child);
+      const childRawLen = child.raw!.length;
+      childOffset += childRawLen;
+    }
+  }
+
+  return { tag, value, children, raw };
+}
+
+export function tlvDecodeAll(data: Uint8Array): TlvNode[] {
+  const nodes: TlvNode[] = [];
+  let offset = 0;
+  while (offset < data.length) {
+    const node = tlvDecode(data, offset);
+    nodes.push(node);
+    offset += node.raw!.length;
+  }
+  return nodes;
+}
+
+export function tlvFind(node: TlvNode, tag: number): TlvNode | undefined {
+  if (!node.children) return undefined;
+  return node.children.find((c) => c.tag === tag);
+}
+
+export function tlvFindAll(node: TlvNode, tag: number): TlvNode[] {
+  if (!node.children) return [];
+  return node.children.filter((c) => c.tag === tag);
+}
+
+export function tlvConcat(...parts: Uint8Array[]): Uint8Array {
+  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+
+export function tlvBuildTagList(tags: number[]): Uint8Array {
+  const tagBytes: Uint8Array[] = tags.map(encodeTag);
+  const value = tlvConcat(...tagBytes);
+  return tlvEncode(0x5c, value);
+}