@particle/esim-tooling 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# @particle/esim-tooling
+
+TypeScript library for eSIM profile provisioning (SGP.22). Manages eSIM profiles on
+devices with an eUICC — list, enable, disable, delete, and install profiles.
+
+## Installation
+
+```
+npm install @particle/esim-tooling
+```
+
+## Quick Start
+
+```typescript
+import { EsimLpa } from '@particle/esim-tooling';
+import type { DeviceAdapter, ServerAdapter } from '@particle/esim-tooling';
+
+// Create adapters for your environment
+const device: DeviceAdapter = createMyDeviceAdapter();
+const server: ServerAdapter = createMyServerAdapter();
+
+const lpa = new EsimLpa({ device, server });
+
+// List profiles
+const profiles = await lpa.listProfiles();
+for (const p of profiles) {
+  console.log(`${p.iccid} ${p.profileName} [${p.state === 1 ? 'enabled' : 'disabled'}]`);
+}
+
+// Enable a profile
+await lpa.enableProfile('89012345678901234567');
+
+// Disable a profile
+await lpa.disableProfile('89012345678901234567');
+
+// Delete a profile (must be disabled first)
+await lpa.deleteProfile('89012345678901234567');
+
+// Install a new profile
+const result = await lpa.installProfile({
+  activationCode: '1$smdp.example.com$ACTIVATION-TOKEN',
+  onProgress: (p) => console.log(p.step),
+});
+console.log(`Installed: ${result.iccid}`);
+
+// Process pending notifications
+const notifResult = await lpa.processNotifications();
+console.log(`Sent ${notifResult.sent}/${notifResult.total} notifications`);
+```
+
+## Adapters
+
+This library does not directly communicate with devices or servers. You provide
+two adapters that handle I/O.
+
+### DeviceAdapter
+
+Sends a single APDU to the eUICC and returns the response. The library handles
+all higher-level protocol concerns (logical channels, STORE DATA chunking,
+GET RESPONSE chaining, BPP segmentation).
+
+```typescript
+interface DeviceAdapter {
+  sendApdu(apdu: Uint8Array): Promise<Uint8Array>;
+}
+```
+
+**Example: Particle USB adapter**
+
+```typescript
+import { openDeviceById } from 'particle-usb';
+import DeviceOSProtobuf from '@particle/device-os-protobuf';
+
+const proto = {
+  ManagerRequest: DeviceOSProtobuf.schema.system.esim.ManagerRequest,
+  ManagerResponse: DeviceOSProtobuf.schema.system.esim.ManagerResponse,
+};
+
+function createParticleUsbAdapter(device): DeviceAdapter {
+  return {
+    async sendApdu(apdu: Uint8Array): Promise<Uint8Array> {
+      // Encode APDU as protobuf ManagerRequest
+      const request = proto.ManagerRequest.create({ apdu: { data: apdu } });
+      const requestBytes = proto.ManagerRequest.encode(request).finish();
+      const response = await device.sendControlRequest(10, Buffer.from(requestBytes));
+      // Decode protobuf ManagerResponse, return APDU response
+      const managerResponse = proto.ManagerResponse.decode(response.data);
+      return new Uint8Array(managerResponse.apdu.data);
+    }
+  };
+}
+```
+
+### ServerAdapter
+
+Forwards ES9+ ASN.1 DER requests to SM-DP+ servers. SM-DP+ servers use TLS certificates
+signed by the GSMA RSP2 Root CI, which is not in standard system CA stores.
+The adapter owns the entire HTTP lifecycle — URL construction, headers, TLS.
+
+```typescript
+interface ServerAdapter {
+  sendRsp(smdpAddress: string, endpoint: string, requestData: Uint8Array): Promise<ServerResponse>;
+}
+
+interface ServerResponse {
+  statusCode: number;
+  responseData?: Uint8Array;
+}
+```
+
+**Example: direct adapter**
+
+```typescript
+const server: ServerAdapter = {
+  async sendRsp(smdpAddress, endpoint, requestData) {
+    const response = await fetch(`https://${smdpAddress}/gsma/rsp2/asn1`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-gsma-rsp-asn1',
+        'User-Agent': 'gsma-rsp-lpad',
+        'X-Admin-Protocol': 'gsma/rsp/v2.1.0',
+      },
+      body: requestData,
+    });
+    const statusCode = response.status;
+    if (statusCode === 204) return { statusCode };
+    const responseData = new Uint8Array(await response.arrayBuffer());
+    return { statusCode, responseData };
+  }
+};
+```
+
+## API Reference
+
+### `EsimLpa`
+
+| Method | Description |
+|--------|-------------|
+| `getEid()` | Get the 32-character hex EID |
+| `listProfiles()` | List all profiles on the eUICC |
+| `enableProfile(iccid)` | Enable a disabled profile |
+| `disableProfile(iccid)` | Disable the active profile |
+| `deleteProfile(iccid)` | Delete a disabled profile |
+| `installProfile(options)` | Download and install a profile from SM-DP+ |
+| `listNotifications()` | List pending notification metadata |
+| `processNotifications()` | Send all pending notifications to SM-DP+ servers |
+
+### Profile States
+
+| Value | State |
+|-------|-------|
+| 0 | Disabled |
+| 1 | Enabled |
+
+### Notification Events
+
+| Value | Event |
+|-------|-------|
+| 0x80 | Install |
+| 0x40 | Enable |
+| 0x20 | Disable |
+| 0x10 | Delete |
+
+## Error Handling
+
+```typescript
+import { Es10Error, Es9PlusError, DeviceError } from '@particle/esim-tooling';
+
+try {
+  await lpa.enableProfile(iccid);
+} catch (error) {
+  if (error instanceof Es10Error) {
+    // eUICC returned an error (e.g., profile not found, policy violation)
+    console.log('eUICC error:', error.resultCode, error.message);
+  } else if (error instanceof Es9PlusError) {
+    // SM-DP+ server error
+    console.log('Server error:', error.statusCode, error.serverStatus);
+  } else if (error instanceof DeviceError) {
+    // Device communication error
+    console.log('Device error:', error.result);
+  }
+}
+```
+
+## License
+
+Apache-2.0

package/dist/activation-code.d.ts

@@ -0,0 +1,11 @@
+import type { ActivationCode } from './types.js';
+/**
+ * Parse an RSP activation code string per SGP.22 Section 4.1.
+ * Format: LPA:1$<smdpAddress>$<matchingId>[$<smdpOid>][$<ccRequired>]
+ * Per spec, the parser SHALL ignore a delimiter and any further parameters
+ * beyond those it recognizes.
+ */
+export declare function parseActivationCode(code: string): ActivationCode;
+export declare function isValidActivationCode(code: string): boolean;
+export declare function formatActivationCode(params: Omit<ActivationCode, 'format'>): string;
+//# sourceMappingURL=activation-code.d.ts.map

package/dist/activation-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-code.d.ts","sourceRoot":"","sources":["../src/activation-code.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAkChE;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAO3D;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,GAAG,MAAM,CASnF"}

package/dist/activation-code.js

@@ -0,0 +1,56 @@
+import { ActivationCodeError } from './errors.js';
+/**
+ * Parse an RSP activation code string per SGP.22 Section 4.1.
+ * Format: LPA:1$<smdpAddress>$<matchingId>[$<smdpOid>][$<ccRequired>]
+ * Per spec, the parser SHALL ignore a delimiter and any further parameters
+ * beyond those it recognizes.
+ */
+export function parseActivationCode(code) {
+    // Strip optional "LPA:" prefix
+    let input = code;
+    if (input.startsWith('LPA:')) {
+        input = input.substring(4);
+    }
+    const parts = input.split('$');
+    if (parts.length < 3) {
+        throw new ActivationCodeError('Activation code must have at least format, address, and matching ID');
+    }
+    const format = parseInt(parts[0], 10);
+    if (format !== 1) {
+        throw new ActivationCodeError(`Unsupported activation code format: ${format}`);
+    }
+    const smdpAddress = parts[1];
+    if (!smdpAddress) {
+        throw new ActivationCodeError('SM-DP+ address is required');
+    }
+    const matchingId = parts[2];
+    const smdpOid = parts.length > 3 && parts[3] ? parts[3] : undefined;
+    const confirmationCodeRequired = parts.length > 4 && parts[4] === '1';
+    return {
+        format,
+        smdpAddress,
+        matchingId,
+        smdpOid,
+        confirmationCodeRequired,
+    };
+}
+export function isValidActivationCode(code) {
+    try {
+        parseActivationCode(code);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function formatActivationCode(params) {
+    let code = `1$${params.smdpAddress}$${params.matchingId}`;
+    if (params.smdpOid || params.confirmationCodeRequired) {
+        code += `$${params.smdpOid ?? ''}`;
+    }
+    if (params.confirmationCodeRequired) {
+        code += '$1';
+    }
+    return code;
+}
+//# sourceMappingURL=activation-code.js.map

package/dist/activation-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-code.js","sourceRoot":"","sources":["../src/activation-code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,+BAA+B;IAC/B,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,mBAAmB,CAAC,qEAAqE,CAAC,CAAC;IACvG,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,mBAAmB,CAAC,uCAAuC,MAAM,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,mBAAmB,CAAC,4BAA4B,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAE5B,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,MAAM,wBAAwB,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;IAEtE,OAAO;QACL,MAAM;QACN,WAAW;QACX,UAAU;QACV,OAAO;QACP,wBAAwB;KACzB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAsC;IACzE,IAAI,IAAI,GAAG,KAAK,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;IAC1D,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,wBAAwB,EAAE,CAAC;QACtD,IAAI,IAAI,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;IACrC,CAAC;IACD,IAAI,MAAM,CAAC,wBAAwB,EAAE,CAAC;QACpC,IAAI,IAAI,IAAI,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/apdu.d.ts

@@ -0,0 +1,73 @@
+import type { DeviceAdapter } from './types.js';
+/**
+ * APDU transport layer — handles logical channel management, STORE DATA
+ * chunking, GET RESPONSE chaining, and BPP segmentation over a DeviceAdapter
+ * that sends individual APDUs.
+ */
+export declare class ApduTransport {
+    private device;
+    private channel;
+    constructor(device: DeviceAdapter);
+    /**
+     * Send a complete SGP.22 TLV payload to the eUICC and return the complete
+     * TLV response. Handles STORE DATA chunking and GET RESPONSE chaining.
+     */
+    sendCommand(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    loadBoundProfilePackage(bpp: Uint8Array): Promise<Uint8Array | undefined>;
+    /**
+     * Build Segment 1: BF36 header (tag+length) + complete BF23
+     */
+    private buildBppSegment1;
+    /**
+     * Build sequence header (tag+length only, no children)
+     */
+    private buildSequenceHeader;
+    /**
+     * 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 sendBppSegments;
+    /**
+     * 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;
+    /**
+     * Close the logical channel if open.
+     */
+    close(): Promise<void>;
+    private ensureChannel;
+    private openChannel;
+    private selectIsdR;
+    private closeChannel;
+    private closeAllChannels;
+    /**
+     * GlobalPlatform CLA byte for the current logical channel.
+     */
+    private gpCla;
+    /**
+     * Send data via STORE DATA chunking and collect the response via
+     * GET RESPONSE chaining.
+     */
+    private storeDataAndGetResponse;
+}
+//# sourceMappingURL=apdu.d.ts.map

package/dist/apdu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apdu.d.ts","sourceRoot":"","sources":["../src/apdu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAmBhD;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAM;gBAET,MAAM,EAAE,aAAa;IAIjC;;;OAGG;IACG,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAKxD;;;;;;;;;;;;;;OAcG;IACG,uBAAuB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAmE/E;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;OAOG;YACW,eAAe;IAiF7B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAWd,aAAa;YAiBb,WAAW;YAYX,UAAU;YAuBV,YAAY;YAKZ,gBAAgB;IAc9B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;;OAGG;YACW,uBAAuB;CAyEtC"}