@onekeyfe/hd-core 1.2.0-alpha.20 → 1.2.0-alpha.22

package/src/protocols/protocol-v2/unlockPolicy.ts

@@ -0,0 +1,105 @@
+export type UnlockPolicy = 'none' | 'unlock-before-run' | 'retry-on-locked';
+
+/**
+ * Protocol V2 methods that are safe to replay after a locked response.
+ *
+ * Keep this as an exact allowlist. Name-pattern matching can silently make a new
+ * state-changing method replayable when it happens to share a suffix.
+ */
+export const PROTOCOL_V2_RETRY_ON_LOCKED_METHODS = [
+  'cipherKeyValue',
+  'allNetworkGetAddress',
+  'allNetworkGetAddressByLoop',
+  'btcGetAddress',
+  'btcGetPublicKey',
+  'btcSignMessage',
+  'btcSignPsbt',
+  'btcSignTransaction',
+  'btcVerifyMessage',
+  'confluxGetAddress',
+  'confluxSignMessage',
+  'confluxSignTransaction',
+  'evmGetAddress',
+  'evmGetPublicKey',
+  'evmSignMessage',
+  'evmSignTransaction',
+  'evmSignTypedData',
+  'evmVerifyMessage',
+  'starcoinGetAddress',
+  'starcoinGetPublicKey',
+  'starcoinSignMessage',
+  'starcoinSignTransaction',
+  'starcoinVerifyMessage',
+  'nemGetAddress',
+  'nemSignTransaction',
+  'solGetAddress',
+  'solSignTransaction',
+  'solSignOffchainMessage',
+  'solSignMessage',
+  'stellarGetAddress',
+  'stellarSignTransaction',
+  'tronGetAddress',
+  'tronSignMessage',
+  'tronSignTransaction',
+  'nearGetAddress',
+  'nearSignTransaction',
+  'aptosGetAddress',
+  'aptosGetPublicKey',
+  'aptosSignTransaction',
+  'aptosSignMessage',
+  'aptosSignInMessage',
+  'algoGetAddress',
+  'algoSignTransaction',
+  'cosmosGetAddress',
+  'cosmosGetPublicKey',
+  'cosmosSignTransaction',
+  'xrpGetAddress',
+  'xrpSignTransaction',
+  'suiGetAddress',
+  'suiGetPublicKey',
+  'suiSignMessage',
+  'suiSignTransaction',
+  'cardanoGetAddress',
+  'cardanoGetPublicKey',
+  'cardanoSignTransaction',
+  'cardanoSignMessage',
+  'filecoinGetAddress',
+  'filecoinSignTransaction',
+  'polkadotGetAddress',
+  'polkadotSignTransaction',
+  'kaspaGetAddress',
+  'kaspaSignTransaction',
+  'nexaGetAddress',
+  'nexaSignTransaction',
+  'nostrGetPublicKey',
+  'nostrSignEvent',
+  'nostrEncryptMessage',
+  'nostrDecryptMessage',
+  'nostrSignSchnorr',
+  'lnurlAuth',
+  'nervosGetAddress',
+  'nervosSignTransaction',
+  'dnxGetAddress',
+  'dnxSignTransaction',
+  'tonGetAddress',
+  'tonSignMessage',
+  'tonSignProof',
+  'tonSignData',
+  'scdoGetAddress',
+  'scdoSignTransaction',
+  'scdoSignMessage',
+  'alephiumGetAddress',
+  'alephiumSignTransaction',
+  'alephiumSignMessage',
+  'benfenGetAddress',
+  'benfenGetPublicKey',
+  'benfenSignMessage',
+  'benfenSignTransaction',
+  'neoGetAddress',
+  'neoSignTransaction',
+] as const;
+
+const retryOnLockedMethods = new Set<string>(PROTOCOL_V2_RETRY_ON_LOCKED_METHODS);
+
+export const getProtocolV2UnlockPolicy = (methodName: string): UnlockPolicy =>
+  retryOnLockedMethods.has(methodName) ? 'retry-on-locked' : 'none';

package/src/protocols/protocol-v2/unlockRetry.ts

@@ -25,9 +25,7 @@ export async function runMethodWithUnlockRetry(
 ) {
   const shouldEmitUi = isProtocolV2UiEnabled(method);
   const shouldUnlockBeforeRun =
-    device.isProtocolV2() &&
-    method.unlockPolicy === 'retry-on-locked' &&
-    device.features?.unlocked === false;
+    device.isProtocolV2() && method.unlockPolicy !== 'none' && device.features?.unlocked === false;
 
   if (shouldUnlockBeforeRun) {
     if (shouldEmitUi) {

package/src/protocols/protocol-v2/walletSession.ts

@@ -1,9 +1,10 @@
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
 
+import { DEVICE } from '../../events';
 import { assertCompleteDeviceSession } from './deviceSession';
 import { isDeviceLockedError } from './lockedError';
 
-import type { DeviceSessionGet } from '@onekeyfe/hd-transport';
+import type { DeviceSessionOpen } from '@onekeyfe/hd-transport';
 import type { Device } from '../../device/Device';
 
 export async function requestProtocolV2DeviceStatus(device: Device) {
@@ -16,16 +17,68 @@ export async function refreshProtocolV2DeviceStatus(device: Device) {
   return device.updateProtocolV2Status(status);
 }
 
-const getDeviceSession = async (device: Device, request: DeviceSessionGet) => {
+const negotiateEventlessWalletSession = async (device: Device) => {
+  await device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+    eventless_wallet_session: true,
+  });
+};
+
+const openDeviceSession = async (device: Device, request: DeviceSessionOpen) => {
   try {
-    return await device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
+    return await device.commands.typedCall('DeviceSessionOpen', 'DeviceSession', request);
   } catch (error) {
     if (!isDeviceLockedError(error)) {
       throw error;
     }
     await device.unlockDevice();
-    return device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
+    return device.commands.typedCall('DeviceSessionOpen', 'DeviceSession', request);
+  }
+};
+
+const selectDeviceSession = async (device: Device) => {
+  const existsAttachPinUser = device.features?.attachToPinEnabled === true;
+  const metadata = {
+    source: 'wallet-session-coordinator' as const,
+    reason: 'open-wallet' as const,
+  };
+  const response = await device.commands.promptPassphrase(
+    { existsAttachPinUser, ...metadata },
+    { cancelDeviceOnReject: false }
+  );
+  const hostPassphrase =
+    typeof response.passphrase === 'string' ? response.passphrase.normalize('NFKD') : undefined;
+  const selections = [
+    !!hostPassphrase,
+    response.passphraseOnDevice === true,
+    response.attachPinOnDevice === true,
+  ].filter(Boolean).length;
+
+  if (selections !== 1) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Wallet selection must contain exactly one passphrase access mode.'
+    );
   }
+
+  if (response.attachPinOnDevice) {
+    if (!existsAttachPinUser) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'Attach PIN wallet selection is unavailable on this device.'
+      );
+    }
+    device.emit(DEVICE.ATTACH_PIN_ON_DEVICE, device, metadata);
+    return openDeviceSession(device, { select: { attach_pin_on_device: {} } });
+  }
+
+  if (response.passphraseOnDevice) {
+    device.emit(DEVICE.PASSPHRASE_ON_DEVICE, device, metadata);
+    return openDeviceSession(device, { select: { passphrase_on_device: {} } });
+  }
+
+  return openDeviceSession(device, {
+    select: { host_passphrase: { passphrase: hostPassphrase as string } },
+  });
 };
 
 export async function getProtocolV2WalletSession(
@@ -40,16 +93,19 @@ export async function getProtocolV2WalletSession(
     device.clearInternalState();
   }
 
-  const expectedPassphraseState = options?.expectedPassphraseState ?? device.passphraseState;
+  await negotiateEventlessWalletSession(device);
+
+  if (options?.onlyMainPin) {
+    device.passphraseState = undefined;
+  }
+  const expectedPassphraseState = options?.onlyMainPin
+    ? undefined
+    : options?.expectedPassphraseState ?? device.passphraseState;
 
-  // Unlock with PIN first. DeviceSessionGet operates on the wallet selected by
-  // the device unlock flow; Protocol V2 does not accept a host passphrase here.
   if (device.features?.unlocked === false) {
     await device.unlockDevice();
   }
 
-  // A standard wallet needs no DeviceSession. After unlock confirms passphrase is
-  // disabled, do not create or forward a hidden-wallet passphraseState.
   if (options?.onlyMainPin || device.getCurrentPassphraseProtection() === false) {
     return {
       passphraseState: undefined,
@@ -66,7 +122,7 @@ export async function getProtocolV2WalletSession(
 
   if (cachedSessionId && expectedPassphraseState) {
     try {
-      response = await getDeviceSession(device, { session_id: cachedSessionId });
+      response = await openDeviceSession(device, { resume: { session_id: cachedSessionId } });
       resumed = true;
     } catch (error) {
       device.clearInternalState();
@@ -75,7 +131,7 @@ export async function getProtocolV2WalletSession(
   }
 
   if (!response) {
-    response = await getDeviceSession(device, {});
+    response = await selectDeviceSession(device);
   }
 
   const { message } = response;
@@ -95,7 +151,7 @@ export async function getProtocolV2WalletSession(
     message.btc_test_address,
     device.getCurrentDeviceId(),
     message.session_id,
-    options?.initSession ? null : device.features?.sessionId ?? null
+    options?.initSession ? null : cachedSessionId ?? null
   );
 
   return {

package/src/topLevelInject.ts

@@ -1,6 +1,7 @@
 import EventEmitter from 'events';
 
 import { createCoreApi } from './inject';
+import { unregisterFirmwareUpdateHostBinding } from './api/firmware/FirmwareHostBinding';
 
 import type { ConnectSettings } from './types/settings';
 import type { CoreApi } from './types/api';
@@ -46,14 +47,15 @@ export const topLevelInject = () => {
       lowLevelApi?.removeAllListeners(type);
     },
 
-    dispose: () => lowLevelApi?.dispose(),
+    dispose: async () => {
+      unregisterFirmwareUpdateHostBinding();
+      await lowLevelApi?.dispose();
+    },
 
     uiResponse: response => lowLevelApi?.uiResponse(response),
 
     cancel: (connectId?: string) => lowLevelApi?.cancel(connectId),
 
-    cancelOperation: (operationId: string) => lowLevelApi?.cancelOperation(operationId),
-
     updateSettings: settings => lowLevelApi?.updateSettings(settings) ?? Promise.resolve(false),
 
     switchTransport: (env: ConnectSettings['env']) =>

package/src/types/api/checkAllFirmwareRelease.ts

@@ -2,6 +2,7 @@ import type { IBLEFirmwareReleaseInfo } from '../settings';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
 import type { CommonParams, Response } from '../params';
 import type { Features, IDeviceBLEFirmwareStatus, IDeviceFirmwareStatus } from '../device';
+import type { FirmwareUpdatePlan } from './firmwareUpdatePlan';
 
 export type FirmwareRelease = {
   shouldUpdate?: boolean;
@@ -20,11 +21,13 @@ export type AllFirmwareRelease = {
   bootloader?: FirmwareRelease;
   bridge?: FirmwareRelease;
   features?: Features;
+  firmwareUpdatePlan?: FirmwareUpdatePlan;
 };
 
 export type CheckAllFirmwareReleaseParams = {
   checkBridgeRelease?: boolean;
   firmwareType?: EFirmwareType;
+  platform?: 'native' | 'desktop' | 'ext' | 'web' | 'web-embed';
 };
 
 export declare function checkAllFirmwareRelease(

package/src/types/api/deviceSettings.ts

@@ -1,28 +1,43 @@
-import type { SafetyCheckLevel, Success } from '@onekeyfe/hd-transport';
+import type { Enum_SafetyCheckLevel, Success } from '@onekeyfe/hd-transport';
 import type { CommonParams, Response } from '../params';
 
 export type DeviceSettingsParams = {
   language?: string;
   label?: string;
   usePassphrase?: boolean;
+  /** Protocol V1 only. */
   homescreen?: string;
+  /** Protocol V1 only. */
   passphraseSource?: number;
   autoLockDelayMs?: number;
+  /** Protocol V1 only. */
   displayRotation?: number;
+  /** Protocol V1 only. */
   passphraseAlwaysOnDevice?: boolean;
-  safetyChecks?: SafetyCheckLevel;
+  /** Protocol V1 only. Uses Enum_SafetyCheckLevel numeric values. */
+  safetyChecks?: Enum_SafetyCheckLevel;
+  /** Protocol V1 only; the current Protocol V2 schema has no matching field. */
   experimentalFeatures?: boolean;
   autoShutdownDelayMs?: number;
+  /** Protocol V1 only; opens the legacy device-side brightness flow. */
   changeBrightness?: boolean;
+  /** Protocol V2 only. */
   brightness?: number;
   hapticFeedback?: boolean;
   bluetoothEnabled?: boolean;
+  /** Protocol V2 only; changed through an on-device confirmation page. */
   airgapMode?: boolean;
+  /** Protocol V2 only. */
   animationEnabled?: boolean;
+  /** Protocol V2 only. */
   tapToWake?: boolean;
+  /** Protocol V2 only. */
   deviceNameDisplayEnabled?: boolean;
+  /** Protocol V2 only. */
   fidoEnabled?: boolean;
+  /** Protocol V2 only. */
   usbLockEnabled?: boolean;
+  /** Protocol V2 only. */
   randomKeypad?: boolean;
 };
 

package/src/types/api/deviceUpdateBootloader.ts

@@ -1,9 +1,15 @@
 import type { Success } from '@onekeyfe/hd-transport';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
+import type { FirmwareArtifactReader, FirmwareArtifactReference } from './firmwareUpdate';
+import type { FirmwareUpdatePreparedPlan } from './firmwareUpdatePreparedPlan';
 import type { Response } from '../params';
 
 export type DeviceUpdateBootloaderParams = {
+  preparedPlan?: FirmwareUpdatePreparedPlan;
+  hostBindingGeneration?: number;
   binary?: ArrayBuffer;
+  artifact?: FirmwareArtifactReference;
+  artifactReader?: FirmwareArtifactReader;
   firmwareType?: EFirmwareType;
 };
 

package/src/types/api/export.ts

@@ -25,11 +25,29 @@ export type {
   DeviceUploadResourceResponse,
 } from './deviceUploadResource';
 export type {
+  FirmwareArtifactReader,
+  FirmwareArtifactReference,
+  FirmwareUpdateHostBinding,
+  FirmwareUpdateArtifactParams,
   FirmwareUpdateParams,
   FirmwareUpdateBinaryParams,
   FirmwareUpdateV3Params,
   FirmwareUpdateV4Params,
+  FirmwareUpdateV4Target,
 } from './firmwareUpdate';
+export type {
+  FirmwareUpdatePlan,
+  FirmwareUpdatePlanArtifact,
+  FirmwareUpdatePlanArtifactRole,
+  FirmwareUpdatePlanTarget,
+} from './firmwareUpdatePlan';
+export type {
+  FirmwareUpdatePreparedArtifact,
+  FirmwareUpdatePreparedArtifactInput,
+  FirmwareUpdatePreparedEntry,
+  FirmwareUpdatePreparedPlan,
+} from './firmwareUpdatePreparedPlan';
+export type { FirmwareUpdateCapabilities } from './firmwareUpdateCapabilities';
 export type { AllFirmwareRelease } from './checkAllFirmwareRelease';
 
 export type { AllNetworkAddressParams, AllNetworkGetAddressParams } from './allNetworkGetAddress';

package/src/types/api/firmwareUpdate.ts

@@ -1,14 +1,53 @@
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
 import type { PROTO } from '../../constants';
 import type { Params, Response } from '../params';
+import type { FirmwareUpdatePreparedPlan } from './firmwareUpdatePreparedPlan';
 
 type IUpdateType = 'firmware' | 'ble';
 
+export interface FirmwareArtifactReference {
+  artifactRef: string;
+  size: number;
+  sha256: string;
+}
+
+export interface FirmwareArtifactReader {
+  open(input: { artifactRef: string }): Promise<{
+    readerId: string;
+    size: number;
+  }>;
+  read(input: { readerId: string; offset: number; length: number }): Promise<{
+    data: ArrayBuffer;
+    bytesRead: number;
+    eof: boolean;
+  }>;
+  close(input: { readerId: string }): Promise<void>;
+}
+
+export interface FirmwareUpdateHostBinding {
+  artifactReader: FirmwareArtifactReader;
+}
+
 export interface FirmwareUpdateBinaryParams {
   binary: ArrayBuffer;
   updateType: IUpdateType;
 }
 
+export interface FirmwareUpdateArtifactParams {
+  preparedPlan: FirmwareUpdatePreparedPlan;
+  hostBindingGeneration: number;
+  artifact: FirmwareArtifactReference;
+  resourceArtifact?: FirmwareArtifactReference;
+  resourceEntries?: Array<{
+    entryName: string;
+    artifact: FirmwareArtifactReference;
+  }>;
+  updateType: IUpdateType;
+  forcedUpdateRes?: boolean;
+  isUpdateBootloader?: boolean;
+  firmwareType?: EFirmwareType;
+}
+
 export interface FirmwareUpdateParams {
   version?: number[];
   updateType: IUpdateType;
@@ -37,8 +76,14 @@ export declare function firmwareUpdateV2(
   connectId: string | undefined,
   params: Params<FirmwareUpdateBinaryParams & Platform>
 ): Response<PROTO.Success>;
+export declare function firmwareUpdateV2(
+  connectId: string | undefined,
+  params: Params<FirmwareUpdateArtifactParams & Platform>
+): Response<PROTO.Success>;
 
 export interface FirmwareUpdateV3Params {
+  preparedPlan?: FirmwareUpdatePreparedPlan;
+  hostBindingGeneration?: number;
   bleVersion?: number[];
   bleBinary?: ArrayBuffer;
   chunkSize?: number;
@@ -55,6 +100,17 @@ export interface FirmwareUpdateV3Params {
   firmwareType?: EFirmwareType;
 
   platform: IPlatform;
+
+  artifactReader?: FirmwareArtifactReader;
+  artifacts?: {
+    ble?: FirmwareArtifactReference;
+    firmware?: FirmwareArtifactReference;
+    bootloader?: FirmwareArtifactReference;
+    resourceEntries?: Array<{
+      entryName: string;
+      artifact: FirmwareArtifactReference;
+    }>;
+  };
 }
 
 /**
@@ -73,10 +129,14 @@ export type FirmwareUpdateV4Target =
   | 'se04';
 
 export interface FirmwareUpdateV4Params {
+  preparedPlan?: FirmwareUpdatePreparedPlan;
+  hostBindingGeneration?: number;
   platform: IPlatform;
+  expectedDeviceId?: string;
   chunkSize?: number;
   firmwareType?: EFirmwareType;
   targetsToUpdate?: FirmwareUpdateV4Target[];
+  expectedTargetVersions?: Partial<Record<FirmwareUpdateV4Target, string>>;
 
   /** FW_MGMT_TARGET_ROMLOADER = 2; Pro2 cannot install it through firmwareUpdateV4. */
   romloaderBinary?: ArrayBuffer;
@@ -102,8 +162,24 @@ export interface FirmwareUpdateV4Params {
     binary: ArrayBuffer;
     devicePath: string;
   }>;
+  artifactReader?: FirmwareArtifactReader;
+  componentArtifacts?: Partial<
+    Record<Exclude<FirmwareUpdateV4Target, 'resource'>, FirmwareArtifactReference>
+  >;
+  resourceBundleArtifacts?: Array<{
+    name: string;
+    artifact: FirmwareArtifactReference;
+  }>;
 }
 
+export declare function registerFirmwareUpdateHostBinding(
+  binding: FirmwareUpdateHostBinding
+): number;
+
+export declare function unregisterFirmwareUpdateHostBinding(generation?: number): boolean;
+
+export declare function getFirmwareUpdateHostBindingGeneration(): number;
+
 export declare function firmwareUpdateV3(
   connectId: string | undefined,
   params: Params<FirmwareUpdateV3Params>

package/src/types/api/firmwareUpdateCapabilities.ts

@@ -0,0 +1,9 @@
+export interface FirmwareUpdateCapabilities {
+  planSchemaVersion: 2;
+  preparedPlanSchemaVersion: 2;
+  hostBindingProtocolVersion: 2;
+  manifestModes: Array<'external-only' | 'sdk-managed'>;
+  supportsArtifactReader: true;
+}
+
+export declare function getFirmwareUpdateCapabilities(): FirmwareUpdateCapabilities;

package/src/types/api/firmwareUpdatePlan.ts

@@ -0,0 +1,36 @@
+import type { FirmwareUpdateV4Target } from './firmwareUpdate';
+import type { EFirmwareType } from '@onekeyfe/hd-shared';
+
+export type FirmwareUpdatePlanArtifactRole =
+  | 'firmware'
+  | 'ble'
+  | 'bootloader'
+  | 'resource'
+  | 'component'
+  | 'resourceBundle';
+
+export type FirmwareUpdatePlanTarget = 'firmware' | 'ble' | 'bootloader' | FirmwareUpdateV4Target;
+
+export interface FirmwareUpdatePlanArtifact {
+  artifactId: string;
+  role: FirmwareUpdatePlanArtifactRole;
+  target: FirmwareUpdatePlanTarget;
+  url: string;
+  container: 'raw' | 'zip';
+  logicalName?: string;
+  expectedSize?: number;
+  expectedSha256?: string;
+  targetVersion?: string;
+}
+
+export interface FirmwareUpdatePlan {
+  schemaVersion: 2;
+  planDigest: string;
+  executor: 'v2' | 'v3' | 'v4';
+  deviceIdentity: string;
+  deviceModel: string;
+  firmwareType: EFirmwareType;
+  platform: 'native' | 'desktop' | 'ext' | 'web' | 'web-embed';
+  artifacts: FirmwareUpdatePlanArtifact[];
+  targetsToUpdate: FirmwareUpdatePlanTarget[];
+}

package/src/types/api/firmwareUpdatePreparedPlan.ts

@@ -0,0 +1,53 @@
+import type { FirmwareArtifactReference } from './firmwareUpdate';
+import type {
+  FirmwareUpdatePlan,
+  FirmwareUpdatePlanArtifactRole,
+  FirmwareUpdatePlanTarget,
+} from './firmwareUpdatePlan';
+
+export interface FirmwareUpdatePreparedEntry {
+  entryName: string;
+  artifact: FirmwareArtifactReference;
+}
+
+export interface FirmwareUpdatePreparedArtifactInput {
+  artifactId: string;
+  artifact: FirmwareArtifactReference;
+  materializedEntries?: FirmwareUpdatePreparedEntry[];
+}
+
+export interface FirmwareUpdatePreparedArtifact {
+  artifactId: string;
+  role: FirmwareUpdatePlanArtifactRole;
+  target: FirmwareUpdatePlanTarget;
+  container: 'raw' | 'zip';
+  logicalName?: string;
+  targetVersion?: string;
+  artifact: FirmwareArtifactReference;
+  materializedEntries?: FirmwareUpdatePreparedEntry[];
+}
+
+export interface FirmwareUpdatePreparedPlan {
+  schemaVersion: 2;
+  preparedPlanDigest: string;
+  planDigest: string;
+  networkPolicy: 'forbid';
+  executor: FirmwareUpdatePlan['executor'];
+  deviceIdentity: string;
+  deviceModel: string;
+  firmwareType: FirmwareUpdatePlan['firmwareType'];
+  platform: FirmwareUpdatePlan['platform'];
+  leaseRef: string;
+  artifacts: FirmwareUpdatePreparedArtifact[];
+  targetsToUpdate: FirmwareUpdatePlanTarget[];
+}
+
+export declare function prepareFirmwareUpdatePlan(input: {
+  plan: FirmwareUpdatePlan;
+  leaseRef: string;
+  artifacts: FirmwareUpdatePreparedArtifactInput[];
+}): FirmwareUpdatePreparedPlan;
+
+export declare function validateFirmwareUpdatePreparedPlan(
+  value: unknown
+): FirmwareUpdatePreparedPlan;