@onekeyfe/hwk-trezor-adapter 1.1.34-alpha.2 → 1.1.34-alpha.4

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { IHardwareWallet, IConnector, TransportType, DeviceInfo, Response, ChainCapability, AllNetworkGetAddressParams, AllNetworkAddressResponse, TrezorDeviceSettingsParams, TrezorBrightnessParams, TrezorChangePinParams, UiResponseEvent, ChainForFingerprint, ICommonCallParams, EvmGetAddressParams, EvmAddress, EvmSignTxTrezorParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, EvmEthereumDefinitions, ConnectorDevice } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, DeviceInfo, Response, ChainCapability, AllNetworkGetAddressParams, AllNetworkAddressResponse, DeviceAuthenticityParams, DeviceAuthenticityResult, TrezorDeviceSettingsParams, TrezorBrightnessParams, TrezorChangePinParams, UiResponseEvent, ChainForFingerprint, ICommonCallParams, EvmGetAddressParams, EvmAddress, EvmSignTxTrezorParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, EvmEthereumDefinitions, ConnectorDevice } from '@onekeyfe/hwk-adapter-core';
 
 type TrezorPassphraseCallParams = {
     passphraseState?: string;
@@ -45,6 +45,7 @@ declare class TrezorAdapter implements IHardwareWallet {
     private static _isStaleSessionError;
     private static _errorCode;
     private static _isConnectionUnavailableError;
+    private static _isRecoverableProtocolResidueError;
     /**
      * Race a promise against an abort signal. Copied from LedgerAdapter:
      * IConnector.call() can't actually be cancelled at the protocol level, but
@@ -73,6 +74,21 @@ declare class TrezorAdapter implements IHardwareWallet {
     getSupportedChains(): ChainCapability[];
     allNetworkGetAddress(connectId: string, deviceId: string, params: AllNetworkGetAddressParams): Promise<Response<AllNetworkAddressResponse[]>>;
     getFeatures(connectId: string): Promise<Response<Record<string, unknown>>>;
+    /**
+     * Device authenticity attestation. Sends a host-generated challenge, has the
+     * device sign it with its secure-element key, then verifies the returned
+     * certificate chain up to a trusted Trezor root CA. On success returns a
+     * `deviceId` that uniquely identifies the physical device, survives wipe, and
+     * cannot be forged from a seed. Only trust the result when `verified` is true
+     * (and `usedDebugKey` is false in production).
+     *
+     * Requires a secure-element model (Safe 3 = T2B1/T3B1, Safe 5 = T3T1, T3W1)
+     * and an on-device confirmation. Older models (T1B1, T2T1) will fail.
+     *
+     * `dangerouslyAllowDebugKeys` accepts simulator / development root keys — NEVER
+     * enable it in a production accounting flow, it lets an emulator mint any id.
+     */
+    verifyDeviceAuthenticity(connectId: string, params?: DeviceAuthenticityParams): Promise<Response<DeviceAuthenticityResult>>;
     deviceSettings(connectId: string, params: TrezorDeviceSettingsParams): Promise<Response<Record<string, unknown>>>;
     setBrightness(connectId: string, params?: TrezorBrightnessParams): Promise<Response<Record<string, unknown>>>;
     changePin(connectId: string, params?: TrezorChangePinParams): Promise<Response<Record<string, unknown>>>;
@@ -87,13 +103,14 @@ declare class TrezorAdapter implements IHardwareWallet {
      */
     uiResponse(response: UiResponseEvent): void;
     /**
-     * Returns the Trezor `device_id` from Features — a random 12-byte value the
-     * device stores and regenerates on `wipe_device`. It identifies the PHYSICAL
-     * DEVICE, not a seed/wallet: it is shared across passphrase wallets and
-     * changes after wipe/restore, so it suits device-match checks but must NOT be
-     * used as a wallet fingerprint (use `passphraseState` for wallet identity).
-     * Unlike Ledger (which hashes a per-chain address), it is chain-global, so
-     * `chain` is accepted for API parity but ignored.
+     * Returns a stable per-seed identifier suitable for device-match verification.
+     *
+     * Trezor exposes `device_id` in Features — a server-generated UUID written
+     * during `wipe_device` and stable for the life of the seed. Unlike Ledger
+     * (no native id, so a per-chain address is hashed), Trezor's id is global
+     * across chains, so the `chain` argument is accepted for API parity but
+     * ignored. For unsupported chains we still surface the id (since it would
+     * be the same value anyway).
      */
     getChainFingerprint(connectId: string, _deviceId: string, _chain: ChainForFingerprint): Promise<Response<string>>;
     /**
@@ -189,6 +206,78 @@ declare class TrezorAdapter implements IHardwareWallet {
     private _ensureDevicePermission;
 }
 
+type CertPubKeys = {
+    rootPubKeysOptiga: string[];
+    rootPubKeysTropic?: string[];
+};
+type ModelPubKeys = CertPubKeys & {
+    debug?: CertPubKeys;
+};
+interface DeviceAuthenticityConfig {
+    version: number;
+    [model: string]: ModelPubKeys | number | undefined;
+}
+
+/** Raw fields taken from a Trezor `AuthenticityProof` message. */
+type AuthenticityProof = {
+    optiga_certificates: string[];
+    optiga_signature: string;
+    tropic_certificates?: string[];
+    tropic_signature?: string;
+    mcu_certificates?: string[];
+    mcu_signature?: string;
+};
+type AuthenticateDeviceResult = {
+    /**
+     * True only when every layer implemented by this verifier and required by
+     * the explicit model policy verified up to a trusted Trezor root CA AND the
+     * device signed our challenge:
+     *  - Optiga (all secure-element models), and
+     *  - Tropic (T3W1 / Safe 7).
+     * This mirrors Trezor Connect's production authenticity policy. The raw MCU
+     * fields remain in the returned proof but are not a client-side pass/fail
+     * condition.
+     * The reward backend must independently verify the same raw proof under its
+     * own versioned policy; this client result is only a UX preview.
+     */
+    verified: boolean;
+    /**
+     * Stable per-device identifier: the X.509 serial number (OID 2.5.4.5) when
+     * present (T3W1+), otherwise the SHA-256 of the device attestation public key.
+     * Survives wipe/recovery and cannot be forged from a seed. Do NOT trust when
+     * `verified` is false — it is then attacker-controlled.
+     */
+    deviceId?: string;
+    /** Raw device attestation public key (hex) from the Optiga device certificate. */
+    deviceCertPubKey?: string;
+    /** X.509 subject serial number (hex), only present on T3W1 and above. */
+    serialNumber?: string;
+    rootPubKey?: string;
+    caPubKey?: string;
+    /**
+     * True when the chain matched a DEBUG/staging root key (simulator / dev
+     * device). A production accounting flow must reject verified results that
+     * have `usedDebugKey === true`.
+     */
+    usedDebugKey?: boolean;
+    /** Failure reason when `verified` is false. */
+    error?: string;
+};
+declare const getRequiredDeviceAuthenticityLayers: (deviceModel: string) => readonly ('optiga' | 'tropic')[];
+/**
+ * Verify a Trezor `AuthenticityProof` against a challenge and derive a stable
+ * per-device id. `challenge` must be the exact random bytes sent in the
+ * `AuthenticateDevice` request. Never throws — malformed input from a malicious
+ * device is folded into `{ verified: false }`.
+ */
+declare const authenticateDeviceFromProof: ({ proof, challenge, deviceModel, config, allowDebugKeys, }: {
+    proof: AuthenticityProof;
+    challenge: Buffer;
+    deviceModel: string;
+    config?: DeviceAuthenticityConfig | undefined;
+    allowDebugKeys?: boolean | undefined;
+}) => AuthenticateDeviceResult;
+
 /**
  * Opt-in helpers for fetching Trezor Ethereum "definitions" — the SatoshiLabs-
  * signed network/token metadata a Trezor device uses to render friendly names
@@ -323,4 +412,4 @@ declare function isTrezorBleServiceUuid(uuid: string): boolean;
 declare function isTrezorBleDescriptor(descriptor: TrezorBleDescriptor): boolean;
 declare function resolveTrezorBleConnectId(descriptor: TrezorBleDescriptor): string;
 
-export { type BuildEthereumDefinitionsForPathParams, type BuildEthereumDefinitionsForSignTxParams, DEFAULT_ETHEREUM_DEFINITIONS_BASE_URL, DEFAULT_SOLANA_TOKEN_DEFINITION_BASE_URL, type FetchEthereumDefinitionsParams, type FetchLike, type FetchSolanaTokenDefinitionParams, type SdkEvent, type SdkEventListener, type SdkLogEvent, TREZOR_BLE_PACKET_SIZE, TREZOR_BLE_SUPPORTED_MODELS, TREZOR_BLE_UUIDS, TREZOR_SAFE_7_MODEL, TrezorAdapter, type TrezorBleDescriptor, type TrezorBleTransport, type TrezorBleTransportFactory, type TrezorConnectedDevice, type TrezorConnectorDevice, buildEthereumDefinitionsForPath, buildEthereumDefinitionsForSignTx, fetchEthereumDefinitions, fetchSolanaTokenDefinition, getSlip44FromPath, isTrezorBleDescriptor, isTrezorBleServiceUuid, isTrezorBleSupportedModel, isTrezorSafe7BleDescriptor, isTrezorSafe7BleName, normalizeTrezorBleUuid, offSdkEvent, onSdkEvent, resolveTrezorBleConnectId };
+export { type AuthenticateDeviceResult, type AuthenticityProof, type BuildEthereumDefinitionsForPathParams, type BuildEthereumDefinitionsForSignTxParams, DEFAULT_ETHEREUM_DEFINITIONS_BASE_URL, DEFAULT_SOLANA_TOKEN_DEFINITION_BASE_URL, type FetchEthereumDefinitionsParams, type FetchLike, type FetchSolanaTokenDefinitionParams, type SdkEvent, type SdkEventListener, type SdkLogEvent, TREZOR_BLE_PACKET_SIZE, TREZOR_BLE_SUPPORTED_MODELS, TREZOR_BLE_UUIDS, TREZOR_SAFE_7_MODEL, TrezorAdapter, type TrezorBleDescriptor, type TrezorBleTransport, type TrezorBleTransportFactory, type TrezorConnectedDevice, type TrezorConnectorDevice, authenticateDeviceFromProof, buildEthereumDefinitionsForPath, buildEthereumDefinitionsForSignTx, fetchEthereumDefinitions, fetchSolanaTokenDefinition, getRequiredDeviceAuthenticityLayers, getSlip44FromPath, isTrezorBleDescriptor, isTrezorBleServiceUuid, isTrezorBleSupportedModel, isTrezorSafe7BleDescriptor, isTrezorSafe7BleName, normalizeTrezorBleUuid, offSdkEvent, onSdkEvent, resolveTrezorBleConnectId };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IHardwareWallet, IConnector, TransportType, DeviceInfo, Response, ChainCapability, AllNetworkGetAddressParams, AllNetworkAddressResponse, TrezorDeviceSettingsParams, TrezorBrightnessParams, TrezorChangePinParams, UiResponseEvent, ChainForFingerprint, ICommonCallParams, EvmGetAddressParams, EvmAddress, EvmSignTxTrezorParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, EvmEthereumDefinitions, ConnectorDevice } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, DeviceInfo, Response, ChainCapability, AllNetworkGetAddressParams, AllNetworkAddressResponse, DeviceAuthenticityParams, DeviceAuthenticityResult, TrezorDeviceSettingsParams, TrezorBrightnessParams, TrezorChangePinParams, UiResponseEvent, ChainForFingerprint, ICommonCallParams, EvmGetAddressParams, EvmAddress, EvmSignTxTrezorParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, EvmEthereumDefinitions, ConnectorDevice } from '@onekeyfe/hwk-adapter-core';
 
 type TrezorPassphraseCallParams = {
     passphraseState?: string;
@@ -45,6 +45,7 @@ declare class TrezorAdapter implements IHardwareWallet {
     private static _isStaleSessionError;
     private static _errorCode;
     private static _isConnectionUnavailableError;
+    private static _isRecoverableProtocolResidueError;
     /**
      * Race a promise against an abort signal. Copied from LedgerAdapter:
      * IConnector.call() can't actually be cancelled at the protocol level, but
@@ -73,6 +74,21 @@ declare class TrezorAdapter implements IHardwareWallet {
     getSupportedChains(): ChainCapability[];
     allNetworkGetAddress(connectId: string, deviceId: string, params: AllNetworkGetAddressParams): Promise<Response<AllNetworkAddressResponse[]>>;
     getFeatures(connectId: string): Promise<Response<Record<string, unknown>>>;
+    /**
+     * Device authenticity attestation. Sends a host-generated challenge, has the
+     * device sign it with its secure-element key, then verifies the returned
+     * certificate chain up to a trusted Trezor root CA. On success returns a
+     * `deviceId` that uniquely identifies the physical device, survives wipe, and
+     * cannot be forged from a seed. Only trust the result when `verified` is true
+     * (and `usedDebugKey` is false in production).
+     *
+     * Requires a secure-element model (Safe 3 = T2B1/T3B1, Safe 5 = T3T1, T3W1)
+     * and an on-device confirmation. Older models (T1B1, T2T1) will fail.
+     *
+     * `dangerouslyAllowDebugKeys` accepts simulator / development root keys — NEVER
+     * enable it in a production accounting flow, it lets an emulator mint any id.
+     */
+    verifyDeviceAuthenticity(connectId: string, params?: DeviceAuthenticityParams): Promise<Response<DeviceAuthenticityResult>>;
     deviceSettings(connectId: string, params: TrezorDeviceSettingsParams): Promise<Response<Record<string, unknown>>>;
     setBrightness(connectId: string, params?: TrezorBrightnessParams): Promise<Response<Record<string, unknown>>>;
     changePin(connectId: string, params?: TrezorChangePinParams): Promise<Response<Record<string, unknown>>>;
@@ -87,13 +103,14 @@ declare class TrezorAdapter implements IHardwareWallet {
      */
     uiResponse(response: UiResponseEvent): void;
     /**
-     * Returns the Trezor `device_id` from Features — a random 12-byte value the
-     * device stores and regenerates on `wipe_device`. It identifies the PHYSICAL
-     * DEVICE, not a seed/wallet: it is shared across passphrase wallets and
-     * changes after wipe/restore, so it suits device-match checks but must NOT be
-     * used as a wallet fingerprint (use `passphraseState` for wallet identity).
-     * Unlike Ledger (which hashes a per-chain address), it is chain-global, so
-     * `chain` is accepted for API parity but ignored.
+     * Returns a stable per-seed identifier suitable for device-match verification.
+     *
+     * Trezor exposes `device_id` in Features — a server-generated UUID written
+     * during `wipe_device` and stable for the life of the seed. Unlike Ledger
+     * (no native id, so a per-chain address is hashed), Trezor's id is global
+     * across chains, so the `chain` argument is accepted for API parity but
+     * ignored. For unsupported chains we still surface the id (since it would
+     * be the same value anyway).
      */
     getChainFingerprint(connectId: string, _deviceId: string, _chain: ChainForFingerprint): Promise<Response<string>>;
     /**
@@ -189,6 +206,78 @@ declare class TrezorAdapter implements IHardwareWallet {
     private _ensureDevicePermission;
 }
 
+type CertPubKeys = {
+    rootPubKeysOptiga: string[];
+    rootPubKeysTropic?: string[];
+};
+type ModelPubKeys = CertPubKeys & {
+    debug?: CertPubKeys;
+};
+interface DeviceAuthenticityConfig {
+    version: number;
+    [model: string]: ModelPubKeys | number | undefined;
+}
+
+/** Raw fields taken from a Trezor `AuthenticityProof` message. */
+type AuthenticityProof = {
+    optiga_certificates: string[];
+    optiga_signature: string;
+    tropic_certificates?: string[];
+    tropic_signature?: string;
+    mcu_certificates?: string[];
+    mcu_signature?: string;
+};
+type AuthenticateDeviceResult = {
+    /**
+     * True only when every layer implemented by this verifier and required by
+     * the explicit model policy verified up to a trusted Trezor root CA AND the
+     * device signed our challenge:
+     *  - Optiga (all secure-element models), and
+     *  - Tropic (T3W1 / Safe 7).
+     * This mirrors Trezor Connect's production authenticity policy. The raw MCU
+     * fields remain in the returned proof but are not a client-side pass/fail
+     * condition.
+     * The reward backend must independently verify the same raw proof under its
+     * own versioned policy; this client result is only a UX preview.
+     */
+    verified: boolean;
+    /**
+     * Stable per-device identifier: the X.509 serial number (OID 2.5.4.5) when
+     * present (T3W1+), otherwise the SHA-256 of the device attestation public key.
+     * Survives wipe/recovery and cannot be forged from a seed. Do NOT trust when
+     * `verified` is false — it is then attacker-controlled.
+     */
+    deviceId?: string;
+    /** Raw device attestation public key (hex) from the Optiga device certificate. */
+    deviceCertPubKey?: string;
+    /** X.509 subject serial number (hex), only present on T3W1 and above. */
+    serialNumber?: string;
+    rootPubKey?: string;
+    caPubKey?: string;
+    /**
+     * True when the chain matched a DEBUG/staging root key (simulator / dev
+     * device). A production accounting flow must reject verified results that
+     * have `usedDebugKey === true`.
+     */
+    usedDebugKey?: boolean;
+    /** Failure reason when `verified` is false. */
+    error?: string;
+};
+declare const getRequiredDeviceAuthenticityLayers: (deviceModel: string) => readonly ('optiga' | 'tropic')[];
+/**
+ * Verify a Trezor `AuthenticityProof` against a challenge and derive a stable
+ * per-device id. `challenge` must be the exact random bytes sent in the
+ * `AuthenticateDevice` request. Never throws — malformed input from a malicious
+ * device is folded into `{ verified: false }`.
+ */
+declare const authenticateDeviceFromProof: ({ proof, challenge, deviceModel, config, allowDebugKeys, }: {
+    proof: AuthenticityProof;
+    challenge: Buffer;
+    deviceModel: string;
+    config?: DeviceAuthenticityConfig | undefined;
+    allowDebugKeys?: boolean | undefined;
+}) => AuthenticateDeviceResult;
+
 /**
  * Opt-in helpers for fetching Trezor Ethereum "definitions" — the SatoshiLabs-
  * signed network/token metadata a Trezor device uses to render friendly names
@@ -323,4 +412,4 @@ declare function isTrezorBleServiceUuid(uuid: string): boolean;
 declare function isTrezorBleDescriptor(descriptor: TrezorBleDescriptor): boolean;
 declare function resolveTrezorBleConnectId(descriptor: TrezorBleDescriptor): string;
 
-export { type BuildEthereumDefinitionsForPathParams, type BuildEthereumDefinitionsForSignTxParams, DEFAULT_ETHEREUM_DEFINITIONS_BASE_URL, DEFAULT_SOLANA_TOKEN_DEFINITION_BASE_URL, type FetchEthereumDefinitionsParams, type FetchLike, type FetchSolanaTokenDefinitionParams, type SdkEvent, type SdkEventListener, type SdkLogEvent, TREZOR_BLE_PACKET_SIZE, TREZOR_BLE_SUPPORTED_MODELS, TREZOR_BLE_UUIDS, TREZOR_SAFE_7_MODEL, TrezorAdapter, type TrezorBleDescriptor, type TrezorBleTransport, type TrezorBleTransportFactory, type TrezorConnectedDevice, type TrezorConnectorDevice, buildEthereumDefinitionsForPath, buildEthereumDefinitionsForSignTx, fetchEthereumDefinitions, fetchSolanaTokenDefinition, getSlip44FromPath, isTrezorBleDescriptor, isTrezorBleServiceUuid, isTrezorBleSupportedModel, isTrezorSafe7BleDescriptor, isTrezorSafe7BleName, normalizeTrezorBleUuid, offSdkEvent, onSdkEvent, resolveTrezorBleConnectId };
+export { type AuthenticateDeviceResult, type AuthenticityProof, type BuildEthereumDefinitionsForPathParams, type BuildEthereumDefinitionsForSignTxParams, DEFAULT_ETHEREUM_DEFINITIONS_BASE_URL, DEFAULT_SOLANA_TOKEN_DEFINITION_BASE_URL, type FetchEthereumDefinitionsParams, type FetchLike, type FetchSolanaTokenDefinitionParams, type SdkEvent, type SdkEventListener, type SdkLogEvent, TREZOR_BLE_PACKET_SIZE, TREZOR_BLE_SUPPORTED_MODELS, TREZOR_BLE_UUIDS, TREZOR_SAFE_7_MODEL, TrezorAdapter, type TrezorBleDescriptor, type TrezorBleTransport, type TrezorBleTransportFactory, type TrezorConnectedDevice, type TrezorConnectorDevice, authenticateDeviceFromProof, buildEthereumDefinitionsForPath, buildEthereumDefinitionsForSignTx, fetchEthereumDefinitions, fetchSolanaTokenDefinition, getRequiredDeviceAuthenticityLayers, getSlip44FromPath, isTrezorBleDescriptor, isTrezorBleServiceUuid, isTrezorBleSupportedModel, isTrezorSafe7BleDescriptor, isTrezorSafe7BleName, normalizeTrezorBleUuid, offSdkEvent, onSdkEvent, resolveTrezorBleConnectId };