@particle/esim-tooling 1.0.0

package/src/apdu.ts

@@ -0,0 +1,419 @@
+import type { DeviceAdapter } from './types.js';
+import { DeviceError } from './errors.js';
+import { tlvDecode, tlvFind, tlvConcat, type TlvNode } from './tlv.js';
+
+// ISD-R AID per SGP.22
+const ISD_R_AID = new Uint8Array([
+  0xa0, 0x00, 0x00, 0x05, 0x59, 0x10, 0x10,
+  0xff, 0xff, 0xff, 0xff, 0x89, 0x00, 0x00, 0x01, 0x00,
+]);
+
+const STORE_DATA_MSS = 255; // max APDU data size per SGP.22
+
+// BPP segment tags (children of BF36 BoundProfilePackage)
+const TAG_BPP_INIT_SECURE_CHANNEL = 0xbf23;
+const TAG_BPP_FIRST_SEQ_OF_87 = 0xa0;
+const TAG_BPP_SEQ_OF_88 = 0xa1;
+const TAG_BPP_SECOND_SEQ_OF_87 = 0xa2;
+const TAG_BPP_SEQ_OF_86 = 0xa3;
+
+/**
+ * APDU transport layer — handles logical channel management, STORE DATA
+ * chunking, GET RESPONSE chaining, and BPP segmentation over a DeviceAdapter
+ * that sends individual APDUs.
+ */
+export class ApduTransport {
+  private device: DeviceAdapter;
+  private channel = -1;
+
+  constructor(device: DeviceAdapter) {
+    this.device = device;
+  }
+
+  /**
+   * Send a complete SGP.22 TLV payload to the eUICC and return the complete
+   * TLV response. Handles STORE DATA chunking and GET RESPONSE chaining.
+   */
+  async sendCommand(data: Uint8Array): Promise<Uint8Array> {
+    await this.ensureChannel();
+    return this.storeDataAndGetResponse(data);
+  }
+
+  /**
+   * Load BPP per SGP.22 Section 2.5.5 Segmented BPP loading.
+   *
+   * Segmentation order:
+   * 1. BF36 header + BF23 (InitialiseSecureChannel)
+   * 2. A0 complete (firstSequenceOf87)
+   * 3. A1 header only (sequenceOf88)
+   * 4. Each 88 TLV individually
+   * 5. A2 complete if present (secondSequenceOf87)
+   * 6. A3 header only (sequenceOf86)
+   * 7. Each 86 TLV individually
+   *
+   * Critical: P1=0x91 only on the VERY LAST APDU of entire BPP.
+   * Block number (P2) resets at each segment boundary.
+   */
+  async loadBoundProfilePackage(bpp: Uint8Array): Promise<Uint8Array | undefined> {
+    await this.ensureChannel();
+
+    const bppNode = tlvDecode(bpp);
+    if (bppNode.tag !== 0xbf36) {
+      throw new DeviceError(-1, `Expected BPP tag BF36, got ${bppNode.tag.toString(16)}`);
+    }
+    if (!bppNode.children || bppNode.children.length === 0) {
+      throw new DeviceError(-1, 'BPP has no children');
+    }
+
+    // Extract required children
+    const initSecureChannel = tlvFind(bppNode, TAG_BPP_INIT_SECURE_CHANNEL);
+    const firstSeq87 = tlvFind(bppNode, TAG_BPP_FIRST_SEQ_OF_87);
+    const seq88 = tlvFind(bppNode, TAG_BPP_SEQ_OF_88);
+    const secondSeq87 = tlvFind(bppNode, TAG_BPP_SECOND_SEQ_OF_87);
+    const seq86 = tlvFind(bppNode, TAG_BPP_SEQ_OF_86);
+
+    if (!initSecureChannel || !firstSeq87 || !seq88 || !seq86) {
+      throw new DeviceError(-1, 'Invalid BPP structure: missing required segments');
+    }
+
+    // Build list of segments per SGP.22 Section 2.5.5
+    const segments: Uint8Array[] = [];
+
+    // Segment 1: BF36 header + BF23 (InitialiseSecureChannel)
+    segments.push(this.buildBppSegment1(bppNode, initSecureChannel));
+
+    // Segment 2: A0 complete (firstSequenceOf87)
+    if (firstSeq87.raw) {
+      segments.push(firstSeq87.raw);
+    }
+
+    // Segment 3: A1 header only (sequenceOf88)
+    segments.push(this.buildSequenceHeader(seq88));
+
+    // Segment 4-N: Each 88 TLV individually
+    if (seq88.children) {
+      for (const child of seq88.children) {
+        if (child.raw) {
+          segments.push(child.raw);
+        }
+      }
+    }
+
+    // Segment N+1: A2 complete if present (secondSequenceOf87)
+    if (secondSeq87?.raw) {
+      segments.push(secondSeq87.raw);
+    }
+
+    // Segment N+2: A3 header only (sequenceOf86)
+    segments.push(this.buildSequenceHeader(seq86));
+
+    // Remaining segments: Each 86 TLV individually
+    if (seq86.children) {
+      for (const child of seq86.children) {
+        if (child.raw) {
+          segments.push(child.raw);
+        }
+      }
+    }
+
+    // Send all segments with proper P1 handling
+    // Returns ProfileInstallationResult (BF37) from the last APDU
+    return await this.sendBppSegments(segments);
+  }
+
+  /**
+   * Build Segment 1: BF36 header (tag+length) + complete BF23
+   */
+  private buildBppSegment1(bppNode: TlvNode, initSecureChannel: TlvNode): Uint8Array {
+    if (!bppNode.raw || !initSecureChannel.raw) {
+      throw new DeviceError(-1, 'BPP or InitialiseSecureChannel missing raw data');
+    }
+
+    // BF36 header = raw minus value
+    const headerSize = bppNode.raw.length - bppNode.value.length;
+    const bppHeader = bppNode.raw.slice(0, headerSize);
+
+    return tlvConcat(bppHeader, initSecureChannel.raw);
+  }
+
+  /**
+   * Build sequence header (tag+length only, no children)
+   */
+  private buildSequenceHeader(node: TlvNode): Uint8Array {
+    if (!node.raw) {
+      throw new DeviceError(-1, 'Node missing raw data');
+    }
+    const headerSize = node.raw.length - node.value.length;
+    return node.raw.slice(0, headerSize);
+  }
+
+  /**
+   * Send BPP segments with correct P1 handling:
+   * - P1=0x11 for all APDUs except the very last
+   * - P1=0x91 only on the VERY LAST APDU of the entire BPP
+   * - P2 resets at each segment boundary
+   *
+   * Returns the ProfileInstallationResult (BF37) from the last APDU response.
+   */
+  private async sendBppSegments(segments: Uint8Array[]): Promise<Uint8Array | undefined> {
+    const cla = this.gpCla();
+    let installationResult: Uint8Array | undefined;
+
+    for (let segIdx = 0; segIdx < segments.length; segIdx++) {
+      const segment = segments[segIdx];
+      const isLastSegment = segIdx === segments.length - 1;
+      const numChunks = Math.max(1, Math.ceil(segment.length / STORE_DATA_MSS));
+
+      for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
+        const offset = chunkIdx * STORE_DATA_MSS;
+        const chunkLen = Math.min(STORE_DATA_MSS, segment.length - offset);
+        const isLastChunk = chunkIdx === numChunks - 1;
+        const isVeryLastApdu = isLastSegment && isLastChunk;
+
+        const apdu = new Uint8Array(5 + chunkLen);
+        apdu[0] = cla;
+        apdu[1] = 0xe2; // STORE DATA
+        apdu[2] = isVeryLastApdu ? 0x91 : 0x11; // P1: only 0x91 on very last APDU
+        apdu[3] = chunkIdx & 0xff; // P2: resets at each segment
+        apdu[4] = chunkLen;
+        apdu.set(segment.subarray(offset, offset + chunkLen), 5);
+
+        const resp = await this.device.sendApdu(apdu);
+        if (resp.length < 2) {
+          throw new DeviceError(-1, `BPP STORE DATA: response too short (segment ${segIdx}, chunk ${chunkIdx})`);
+        }
+
+        let sw1 = resp[resp.length - 2];
+        let sw2 = resp[resp.length - 1];
+
+        // Collect response data for ProfileInstallationResult
+        const responseChunks: Uint8Array[] = [];
+        const initialData = resp.subarray(0, resp.length - 2);
+        if (initialData.length > 0) {
+          responseChunks.push(initialData);
+        }
+
+        // Handle SW=61XX (more data available) by draining with GET RESPONSE
+        while (sw1 === 0x61) {
+          const getResp = await this.device.sendApdu(new Uint8Array([cla, 0xc0, 0x00, 0x00, sw2]));
+          if (getResp.length < 2) {
+            throw new DeviceError(-1, `BPP GET RESPONSE too short (segment ${segIdx}, chunk ${chunkIdx})`);
+          }
+
+          const respData = getResp.subarray(0, getResp.length - 2);
+          if (respData.length > 0) {
+            responseChunks.push(respData);
+          }
+
+          sw1 = getResp[getResp.length - 2];
+          sw2 = getResp[getResp.length - 1];
+        }
+
+        // Per SGP.22: accept SW 90XX or 91XX
+        if (sw1 !== 0x90 && sw1 !== 0x91) {
+          throw new DeviceError(-1, `BPP segment ${segIdx} chunk ${chunkIdx} failed: SW=${sw1.toString(16)}${sw2.toString(16)}`);
+        }
+
+        // Collect response data if present
+        if (responseChunks.length > 0) {
+          const totalLen = responseChunks.reduce((sum, c) => sum + c.length, 0);
+          installationResult = new Uint8Array(totalLen);
+          let pos = 0;
+          for (const chunk of responseChunks) {
+            installationResult.set(chunk, pos);
+            pos += chunk.length;
+          }
+
+          // If we got a ProfileInstallationResult (BF37), stop sending - eUICC has responded
+          // This handles both early errors and final success/failure
+          if (this.isBppResult(installationResult)) {
+            return installationResult;
+          }
+        }
+      }
+    }
+
+    return installationResult;
+  }
+
+  /**
+   * Check if BPP response data contains a ProfileInstallationResult (BF37).
+   * Returns true if BF37 is detected (caller should stop sending and return the data).
+   */
+  private isBppResult(data: Uint8Array): boolean {
+    // Look for BF37 tag (ProfileInstallationResult)
+    // BF37 = 0xBF 0x37
+    if (data.length < 4) return false;
+    return data[0] === 0xbf && data[1] === 0x37;
+  }
+
+  /**
+   * Close the logical channel if open.
+   */
+  async close(): Promise<void> {
+    if (this.channel >= 0) {
+      await this.closeChannel(this.channel);
+      this.channel = -1;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Logical channel management
+  // ---------------------------------------------------------------------------
+
+  private async ensureChannel(): Promise<void> {
+    if (this.channel >= 0) return;
+
+    let ch = await this.openChannel();
+    if (ch < 0) {
+      // Stale channels from a previous run — close all and retry
+      await this.closeAllChannels();
+      ch = await this.openChannel();
+      if (ch < 0) {
+        throw new DeviceError(-1, 'Failed to open logical channel');
+      }
+    }
+
+    await this.selectIsdR(ch);
+    this.channel = ch;
+  }
+
+  private async openChannel(): Promise<number> {
+    // MANAGE CHANNEL OPEN: 00 70 00 00 01
+    const resp = await this.device.sendApdu(new Uint8Array([0x00, 0x70, 0x00, 0x00, 0x01]));
+    if (resp.length < 3) return -1;
+
+    const sw1 = resp[resp.length - 2];
+    const sw2 = resp[resp.length - 1];
+    if (sw1 !== 0x90 || sw2 !== 0x00) return -1;
+
+    return resp[0];
+  }
+
+  private async selectIsdR(channel: number): Promise<void> {
+    // SELECT: CLA=channel, INS=A4, P1=04, P2=00, Lc=AID_len, Data=AID, Le=00
+    const cmd = new Uint8Array(5 + ISD_R_AID.length + 1);
+    cmd[0] = channel <= 3 ? (0x00 | channel) : (0x40 | (channel - 4));
+    cmd[1] = 0xa4;
+    cmd[2] = 0x04;
+    cmd[3] = 0x00;
+    cmd[4] = ISD_R_AID.length;
+    cmd.set(ISD_R_AID, 5);
+    cmd[5 + ISD_R_AID.length] = 0x00; // Le
+
+    const resp = await this.device.sendApdu(cmd);
+    if (resp.length < 2) {
+      throw new DeviceError(-1, 'SELECT ISD-R: response too short');
+    }
+
+    const sw1 = resp[resp.length - 2];
+    if (sw1 !== 0x90 && sw1 !== 0x61) {
+      const sw2 = resp[resp.length - 1];
+      throw new DeviceError(-1, `SELECT ISD-R failed: SW=${sw1.toString(16)}${sw2.toString(16)}`);
+    }
+  }
+
+  private async closeChannel(channel: number): Promise<void> {
+    // MANAGE CHANNEL CLOSE
+    await this.device.sendApdu(new Uint8Array([0x00, 0x70, 0x80, channel, 0x00]));
+  }
+
+  private async closeAllChannels(): Promise<void> {
+    for (let ch = 1; ch <= 3; ch++) {
+      try {
+        await this.closeChannel(ch);
+      } catch {
+        // Ignore errors — channel may not be open
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // STORE DATA + GET RESPONSE
+  // ---------------------------------------------------------------------------
+
+  /**
+   * GlobalPlatform CLA byte for the current logical channel.
+   */
+  private gpCla(): number {
+    return this.channel <= 3 ? (0x80 | this.channel) : (0xc0 | (this.channel - 4));
+  }
+
+  /**
+   * Send data via STORE DATA chunking and collect the response via
+   * GET RESPONSE chaining.
+   */
+  private async storeDataAndGetResponse(data: Uint8Array): Promise<Uint8Array> {
+    const cla = this.gpCla();
+    const numChunks = Math.max(1, Math.ceil(data.length / STORE_DATA_MSS));
+
+    let lastResp: Uint8Array = new Uint8Array(0);
+
+    for (let i = 0; i < numChunks; i++) {
+      const offset = i * STORE_DATA_MSS;
+      const chunkLen = Math.min(STORE_DATA_MSS, data.length - offset);
+      const isLast = i === numChunks - 1;
+
+      const apdu = new Uint8Array(5 + chunkLen);
+      apdu[0] = cla;
+      apdu[1] = 0xe2; // STORE DATA
+      apdu[2] = isLast ? 0x91 : 0x11; // P1: last or continue
+      apdu[3] = i & 0xff; // P2: sequence number
+      apdu[4] = chunkLen;
+      apdu.set(data.subarray(offset, offset + chunkLen), 5);
+
+      lastResp = await this.device.sendApdu(apdu);
+      if (lastResp.length < 2) {
+        throw new DeviceError(-1, 'STORE DATA: response too short');
+      }
+
+      if (!isLast) {
+        const sw1 = lastResp[lastResp.length - 2];
+        const sw2 = lastResp[lastResp.length - 1];
+        if (sw1 !== 0x90 || sw2 !== 0x00) {
+          throw new DeviceError(-1, `STORE DATA chunk ${i} failed: SW=${sw1.toString(16)}${sw2.toString(16)}`);
+        }
+      }
+    }
+
+    // Collect response data from last STORE DATA and GET RESPONSE chains
+    const parts: Uint8Array[] = [];
+
+    // Data from last STORE DATA (excluding SW)
+    if (lastResp.length > 2) {
+      parts.push(lastResp.subarray(0, lastResp.length - 2));
+    }
+
+    let sw1 = lastResp[lastResp.length - 2];
+    let sw2 = lastResp[lastResp.length - 1];
+
+    // GET RESPONSE chaining
+    while (sw1 === 0x61) {
+      const getResp = await this.device.sendApdu(new Uint8Array([cla, 0xc0, 0x00, 0x00, sw2]));
+      if (getResp.length < 2) {
+        throw new DeviceError(-1, 'GET RESPONSE: response too short');
+      }
+
+      if (getResp.length > 2) {
+        parts.push(getResp.subarray(0, getResp.length - 2));
+      }
+
+      sw1 = getResp[getResp.length - 2];
+      sw2 = getResp[getResp.length - 1];
+    }
+
+    if (sw1 !== 0x90) {
+      throw new DeviceError(-1, `Final SW=${sw1.toString(16)}${sw2.toString(16)}`);
+    }
+
+    // Concatenate all response parts
+    const totalLen = parts.reduce((sum, p) => sum + p.length, 0);
+    const result = new Uint8Array(totalLen);
+    let pos = 0;
+    for (const part of parts) {
+      result.set(part, pos);
+      pos += part.length;
+    }
+    return result;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,69 @@
+export class EsimError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'EsimError';
+    this.code = code;
+  }
+}
+
+export class DeviceError extends EsimError {
+  readonly result: number;
+
+  constructor(result: number, message?: string) {
+    super('DEVICE_ERROR', message ?? `Device error: ${result}`);
+    this.name = 'DeviceError';
+    this.result = result;
+  }
+}
+
+export class Es10Error extends EsimError {
+  readonly resultCode: number;
+
+  constructor(resultCode: number, message?: string) {
+    super('ES10_ERROR', message ?? `eUICC error: ${resultCode}`);
+    this.name = 'Es10Error';
+    this.resultCode = resultCode;
+  }
+}
+
+export class Es9PlusError extends EsimError {
+  readonly statusCode: number;
+  readonly serverStatus?: string;
+  readonly subjectCode?: string;
+  readonly reasonCode?: string;
+
+  constructor(params: {
+    statusCode: number;
+    serverStatus?: string;
+    subjectCode?: string;
+    reasonCode?: string;
+    message?: string;
+  }) {
+    super(
+      'ES9PLUS_ERROR',
+      params.message ??
+        `SM-DP+ error: HTTP ${params.statusCode}${params.serverStatus ? ` (${params.serverStatus})` : ''}`,
+    );
+    this.name = 'Es9PlusError';
+    this.statusCode = params.statusCode;
+    this.serverStatus = params.serverStatus;
+    this.subjectCode = params.subjectCode;
+    this.reasonCode = params.reasonCode;
+  }
+}
+
+export class TlvError extends EsimError {
+  constructor(message: string) {
+    super('TLV_ERROR', message);
+    this.name = 'TlvError';
+  }
+}
+
+export class ActivationCodeError extends EsimError {
+  constructor(message: string) {
+    super('ACTIVATION_CODE_ERROR', message);
+    this.name = 'ActivationCodeError';
+  }
+}