@onekeyfe/hwk-trezor-core 1.1.27-alpha.100

package/README.md

@@ -0,0 +1,5 @@
+# @onekeyfe/hwk-trezor-core
+
+Minimal Trezor message call layer for Hardware Wallet Kit.
+
+This package owns protobuf message encoding, transport framing, chunked writes, and response decoding. It does not depend on Trezor Connect or Connect Mobile.

package/dist/index.d.mts

@@ -0,0 +1,239 @@
+interface TrezorByteTransport {
+    write(chunk: Buffer, signal?: AbortSignal): Promise<void>;
+    read(signal?: AbortSignal): Promise<Buffer>;
+}
+interface TrezorTransportProtocol {
+    name: 'bridge' | 'v1' | 'v2';
+    encode(data: Buffer, options: {
+        messageType: number;
+        header?: Buffer;
+    }): Buffer;
+    decode(bytes: Buffer): {
+        header: Buffer;
+        length: number;
+        messageType: number;
+        payload: Buffer;
+    };
+    getHeaders(data: Buffer): [header: Buffer, chunkHeader: Buffer];
+}
+type TrezorThpState = {
+    readonly sendNonce?: number;
+    sync(direction: 'send' | 'recv', messageName: string): void;
+};
+type TrezorMessageName = string;
+type TrezorMessageResponse<T extends string = string> = {
+    type: T;
+    message: Record<string, unknown>;
+};
+type TrezorCoreOptions = {
+    transport: TrezorByteTransport;
+    protocol?: TrezorTransportProtocol;
+    chunkSize?: number;
+    logger?: TrezorDebugLogger;
+};
+type TrezorCallOptions = {
+    signal?: AbortSignal;
+    thpState?: TrezorThpState;
+};
+type TrezorThpRawTransport = {
+    write?(connectId: string, data: Uint8Array): Promise<void>;
+    read?(connectId: string, timeoutMs?: number): Promise<Uint8Array | undefined>;
+};
+type TrezorThpCallParams = {
+    messageName: string;
+    data?: Record<string, unknown>;
+    skipAck?: boolean;
+};
+type TrezorDebugLogLevel = 'debug' | 'info' | 'warn' | 'error';
+type TrezorDebugLogEntry = {
+    level: TrezorDebugLogLevel;
+    scope: string;
+    event: string;
+    data?: Record<string, unknown>;
+};
+type TrezorDebugLogger = (entry: TrezorDebugLogEntry) => void;
+declare class TrezorFailureError extends Error {
+    readonly code?: unknown;
+    readonly response: TrezorMessageResponse<'Failure'>;
+    constructor(response: TrezorMessageResponse<'Failure'>);
+}
+declare class TrezorCore {
+    private readonly transport;
+    private readonly protocol;
+    private readonly chunkSize;
+    private readonly logger?;
+    constructor({ transport, protocol, chunkSize, logger }: TrezorCoreOptions);
+    call(name: TrezorMessageName, data?: Record<string, unknown>, options?: TrezorCallOptions): Promise<TrezorMessageResponse>;
+    private thpLoopLogger;
+}
+declare class TrezorThpProtocol {
+    private readonly thpState;
+    constructor();
+    encode({ messageName, data }: TrezorThpCallParams): Uint8Array;
+    call(transport: TrezorThpRawTransport, connectId: string, params: TrezorThpCallParams): Promise<TrezorMessageResponse>;
+    private applyReceivedState;
+}
+type TrezorCoreLike = {
+    call(name: string, data?: Record<string, unknown>, options?: TrezorCallOptions): Promise<TrezorMessageResponse>;
+};
+type TrezorCoreFactory = (transport: TrezorByteTransport, protocol: TrezorTransportProtocol, chunkSize: number, logger?: TrezorDebugLogger) => TrezorCoreLike;
+type TrezorSessionProtocol = 'v1' | 'thp';
+type TrezorDeviceSessionOptions = {
+    transport: TrezorByteTransport;
+    connectionType?: string;
+    chunkSize?: number;
+    coreFactory?: TrezorCoreFactory;
+    initializedState?: {
+        protocol: TrezorSessionProtocol;
+        features: Record<string, unknown>;
+        thpState?: TrezorThpState;
+    };
+    thp?: TrezorThpSessionOptions;
+};
+type TrezorThpPairingMethod = number | 'CodeEntry' | 'QrCode' | 'NFC' | 'SkipPairing';
+type TrezorThpCredentials = Record<string, unknown> & {
+    host_static_key?: string;
+    autoconnect?: boolean;
+};
+type TrezorThpHandshakeInitResponse = Record<string, unknown>;
+type TrezorPinMatrixRequestPayload = Record<string, unknown> & {
+    type?: string;
+};
+type TrezorThpHandshakeCredentials = {
+    pairingMethods: number[];
+    handshakeHash: Buffer;
+    handshakeCommitment?: Buffer;
+    codeEntryChallenge?: Buffer;
+    trezorEncryptedStaticPubkey: Buffer;
+    hostEncryptedStaticPubkey: Buffer;
+    staticKey: Buffer;
+    hostStaticPublicKey?: Buffer;
+    hostKey: Buffer;
+    trezorKey: Buffer;
+    trezorCpacePublicKey?: Buffer;
+};
+type TrezorThpHandshakeInitHandler = (args: {
+    handshakeInitResponse: TrezorThpHandshakeInitResponse;
+    thpState: TrezorThpState;
+    knownCredentials: TrezorThpCredentials[];
+    hostEphemeralKeys: {
+        privateKey: Buffer;
+        publicKey: Buffer;
+    };
+    tryToUnlock: 0 | 1;
+    protobufEncoder: (name: string, data: Record<string, unknown>) => {
+        message: Buffer;
+    };
+}) => {
+    trezorMaskedStaticPubkey: Buffer;
+    trezorEncryptedStaticPubkey: Buffer;
+    hostEncryptedStaticPubkey: Buffer;
+    hostKey: Buffer;
+    trezorKey: Buffer;
+    handshakeHash: Buffer;
+    credentials?: TrezorThpCredentials;
+    allCredentials: TrezorThpCredentials[];
+    encryptedPayload: Buffer;
+    staticKey: Buffer;
+    hostStaticKeys: {
+        privateKey: Buffer;
+        publicKey: Buffer;
+    };
+};
+type TrezorThpPairingResponse = {
+    selectedMethod: TrezorThpPairingMethod;
+} | {
+    tag: string;
+};
+type TrezorThpSessionOptions = {
+    hostName?: string;
+    appName?: string;
+    pairingMethods?: TrezorThpPairingMethod[];
+    knownCredentials?: TrezorThpCredentials[];
+    randomBytes?: (size: number) => Buffer;
+    handleHandshakeInit?: TrezorThpHandshakeInitHandler;
+    onPairingRequest?: (payload: {
+        availableMethods: number[];
+        selectedMethod: number;
+        nfcData?: string;
+    }) => Promise<TrezorThpPairingResponse>;
+    onButtonRequest?: (payload: Record<string, unknown>) => Promise<void> | void;
+    onPinMatrixRequest?: (payload: TrezorPinMatrixRequestPayload) => Promise<string> | string;
+    /**
+     * Provide the passphrase for a session. Called at two points depending on
+     * protocol — proactively before `ThpCreateNewSession` (THP), reactively on
+     * a `PassphraseRequest` (v1). Return `{ on_device: true }` to enter the
+     * passphrase on the device instead of sending a value. Empty string = the
+     * standard (no-passphrase) wallet.
+     */
+    onPassphraseRequest?: (payload?: Record<string, unknown>) => Promise<{
+        passphrase?: string;
+        on_device?: boolean;
+    }> | {
+        passphrase?: string;
+        on_device?: boolean;
+    };
+    /**
+     * Invoked after the THP handshake mints fresh pairing credentials (i.e.
+     * the first successful pairing run after a wipe / new device). The host
+     * should persist the full `credentials` list keyed by `deviceId` and feed
+     * it back via `knownCredentials` on the next connect to skip pairing UX.
+     */
+    onPairingCredentialsChanged?: (payload: {
+        credentials: TrezorThpCredentials[];
+    }) => Promise<void> | void;
+    logger?: TrezorDebugLogger;
+};
+declare class TrezorDeviceSession {
+    private readonly transport;
+    private readonly connectionType?;
+    private readonly chunkSize;
+    private readonly coreFactory;
+    private readonly thpOptions?;
+    private core?;
+    private protocol;
+    private thpState?;
+    private thpAppSessionActive;
+    private currentFeatures?;
+    constructor(options: TrezorDeviceSessionOptions);
+    get features(): Record<string, unknown> | undefined;
+    /**
+     * Whether this device speaks THP (v2). THP supports multiple host-managed
+     * application sessions per channel (passphrase sessions); v1 does not — its
+     * passphrase flow is reactive (device-driven `PassphraseRequest`). The
+     * adapter branches on this to decide whether to drive app-session caching.
+     */
+    get isThp(): boolean;
+    getThpState(): TrezorThpState | undefined;
+    initialize(): Promise<Record<string, unknown>>;
+    call(name: string, data?: Record<string, unknown>): Promise<{
+        type: string;
+        message: Record<string, unknown>;
+    }>;
+    private initializeThp;
+    /**
+     * Create a NEW THP application session with a freshly-prompted passphrase
+     * (or empty if the device has no passphrase protection). Returns the new
+     * session id (hex). The session knows nothing about wallet identity (XFP) —
+     * the adapter derives that (via master fingerprint) and owns the
+     * XFP↔sessionId map. Multiple sessions can coexist on one channel.
+     */
+    createThpAppSession(deriveCardano?: boolean): Promise<string>;
+    /**
+     * Switch the active THP session to an existing id (host-side: just sets the
+     * session-id byte in the next message header). The device must still hold
+     * the session — validity is verified by the caller's next real call (an
+     * evicted session surfaces as a Failure/ThpError, the adapter then recreates).
+     */
+    selectThpAppSession(sessionId: string): void;
+    /** Active THP session id (hex), or undefined if none created/selected. */
+    getThpAppSessionId(): string | undefined;
+    private ensureThpApplicationSession;
+    private handleButtonRequest;
+    private handlePinMatrixRequest;
+    private handlePassphraseRequest;
+    private cancelCurrentCall;
+    private log;
+}
+
+export { type TrezorByteTransport, type TrezorCallOptions, TrezorCore, type TrezorCoreFactory, type TrezorCoreLike, type TrezorCoreOptions, type TrezorDebugLogEntry, type TrezorDebugLogLevel, type TrezorDebugLogger, TrezorDeviceSession, TrezorFailureError, type TrezorMessageName, type TrezorMessageResponse, type TrezorPinMatrixRequestPayload, type TrezorThpCallParams, type TrezorThpCredentials, type TrezorThpHandshakeCredentials, type TrezorThpHandshakeInitHandler, type TrezorThpHandshakeInitResponse, type TrezorThpPairingMethod, TrezorThpProtocol, type TrezorThpRawTransport, type TrezorThpSessionOptions, type TrezorThpState, type TrezorTransportProtocol };

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+interface TrezorByteTransport {
+    write(chunk: Buffer, signal?: AbortSignal): Promise<void>;
+    read(signal?: AbortSignal): Promise<Buffer>;
+}
+interface TrezorTransportProtocol {
+    name: 'bridge' | 'v1' | 'v2';
+    encode(data: Buffer, options: {
+        messageType: number;
+        header?: Buffer;
+    }): Buffer;
+    decode(bytes: Buffer): {
+        header: Buffer;
+        length: number;
+        messageType: number;
+        payload: Buffer;
+    };
+    getHeaders(data: Buffer): [header: Buffer, chunkHeader: Buffer];
+}
+type TrezorThpState = {
+    readonly sendNonce?: number;
+    sync(direction: 'send' | 'recv', messageName: string): void;
+};
+type TrezorMessageName = string;
+type TrezorMessageResponse<T extends string = string> = {
+    type: T;
+    message: Record<string, unknown>;
+};
+type TrezorCoreOptions = {
+    transport: TrezorByteTransport;
+    protocol?: TrezorTransportProtocol;
+    chunkSize?: number;
+    logger?: TrezorDebugLogger;
+};
+type TrezorCallOptions = {
+    signal?: AbortSignal;
+    thpState?: TrezorThpState;
+};
+type TrezorThpRawTransport = {
+    write?(connectId: string, data: Uint8Array): Promise<void>;
+    read?(connectId: string, timeoutMs?: number): Promise<Uint8Array | undefined>;
+};
+type TrezorThpCallParams = {
+    messageName: string;
+    data?: Record<string, unknown>;
+    skipAck?: boolean;
+};
+type TrezorDebugLogLevel = 'debug' | 'info' | 'warn' | 'error';
+type TrezorDebugLogEntry = {
+    level: TrezorDebugLogLevel;
+    scope: string;
+    event: string;
+    data?: Record<string, unknown>;
+};
+type TrezorDebugLogger = (entry: TrezorDebugLogEntry) => void;
+declare class TrezorFailureError extends Error {
+    readonly code?: unknown;
+    readonly response: TrezorMessageResponse<'Failure'>;
+    constructor(response: TrezorMessageResponse<'Failure'>);
+}
+declare class TrezorCore {
+    private readonly transport;
+    private readonly protocol;
+    private readonly chunkSize;
+    private readonly logger?;
+    constructor({ transport, protocol, chunkSize, logger }: TrezorCoreOptions);
+    call(name: TrezorMessageName, data?: Record<string, unknown>, options?: TrezorCallOptions): Promise<TrezorMessageResponse>;
+    private thpLoopLogger;
+}
+declare class TrezorThpProtocol {
+    private readonly thpState;
+    constructor();
+    encode({ messageName, data }: TrezorThpCallParams): Uint8Array;
+    call(transport: TrezorThpRawTransport, connectId: string, params: TrezorThpCallParams): Promise<TrezorMessageResponse>;
+    private applyReceivedState;
+}
+type TrezorCoreLike = {
+    call(name: string, data?: Record<string, unknown>, options?: TrezorCallOptions): Promise<TrezorMessageResponse>;
+};
+type TrezorCoreFactory = (transport: TrezorByteTransport, protocol: TrezorTransportProtocol, chunkSize: number, logger?: TrezorDebugLogger) => TrezorCoreLike;
+type TrezorSessionProtocol = 'v1' | 'thp';
+type TrezorDeviceSessionOptions = {
+    transport: TrezorByteTransport;
+    connectionType?: string;
+    chunkSize?: number;
+    coreFactory?: TrezorCoreFactory;
+    initializedState?: {
+        protocol: TrezorSessionProtocol;
+        features: Record<string, unknown>;
+        thpState?: TrezorThpState;
+    };
+    thp?: TrezorThpSessionOptions;
+};
+type TrezorThpPairingMethod = number | 'CodeEntry' | 'QrCode' | 'NFC' | 'SkipPairing';
+type TrezorThpCredentials = Record<string, unknown> & {
+    host_static_key?: string;
+    autoconnect?: boolean;
+};
+type TrezorThpHandshakeInitResponse = Record<string, unknown>;
+type TrezorPinMatrixRequestPayload = Record<string, unknown> & {
+    type?: string;
+};
+type TrezorThpHandshakeCredentials = {
+    pairingMethods: number[];
+    handshakeHash: Buffer;
+    handshakeCommitment?: Buffer;
+    codeEntryChallenge?: Buffer;
+    trezorEncryptedStaticPubkey: Buffer;
+    hostEncryptedStaticPubkey: Buffer;
+    staticKey: Buffer;
+    hostStaticPublicKey?: Buffer;
+    hostKey: Buffer;
+    trezorKey: Buffer;
+    trezorCpacePublicKey?: Buffer;
+};
+type TrezorThpHandshakeInitHandler = (args: {
+    handshakeInitResponse: TrezorThpHandshakeInitResponse;
+    thpState: TrezorThpState;
+    knownCredentials: TrezorThpCredentials[];
+    hostEphemeralKeys: {
+        privateKey: Buffer;
+        publicKey: Buffer;
+    };
+    tryToUnlock: 0 | 1;
+    protobufEncoder: (name: string, data: Record<string, unknown>) => {
+        message: Buffer;
+    };
+}) => {
+    trezorMaskedStaticPubkey: Buffer;
+    trezorEncryptedStaticPubkey: Buffer;
+    hostEncryptedStaticPubkey: Buffer;
+    hostKey: Buffer;
+    trezorKey: Buffer;
+    handshakeHash: Buffer;
+    credentials?: TrezorThpCredentials;
+    allCredentials: TrezorThpCredentials[];
+    encryptedPayload: Buffer;
+    staticKey: Buffer;
+    hostStaticKeys: {
+        privateKey: Buffer;
+        publicKey: Buffer;
+    };
+};
+type TrezorThpPairingResponse = {
+    selectedMethod: TrezorThpPairingMethod;
+} | {
+    tag: string;
+};
+type TrezorThpSessionOptions = {
+    hostName?: string;
+    appName?: string;
+    pairingMethods?: TrezorThpPairingMethod[];
+    knownCredentials?: TrezorThpCredentials[];
+    randomBytes?: (size: number) => Buffer;
+    handleHandshakeInit?: TrezorThpHandshakeInitHandler;
+    onPairingRequest?: (payload: {
+        availableMethods: number[];
+        selectedMethod: number;
+        nfcData?: string;
+    }) => Promise<TrezorThpPairingResponse>;
+    onButtonRequest?: (payload: Record<string, unknown>) => Promise<void> | void;
+    onPinMatrixRequest?: (payload: TrezorPinMatrixRequestPayload) => Promise<string> | string;
+    /**
+     * Provide the passphrase for a session. Called at two points depending on
+     * protocol — proactively before `ThpCreateNewSession` (THP), reactively on
+     * a `PassphraseRequest` (v1). Return `{ on_device: true }` to enter the
+     * passphrase on the device instead of sending a value. Empty string = the
+     * standard (no-passphrase) wallet.
+     */
+    onPassphraseRequest?: (payload?: Record<string, unknown>) => Promise<{
+        passphrase?: string;
+        on_device?: boolean;
+    }> | {
+        passphrase?: string;
+        on_device?: boolean;
+    };
+    /**
+     * Invoked after the THP handshake mints fresh pairing credentials (i.e.
+     * the first successful pairing run after a wipe / new device). The host
+     * should persist the full `credentials` list keyed by `deviceId` and feed
+     * it back via `knownCredentials` on the next connect to skip pairing UX.
+     */
+    onPairingCredentialsChanged?: (payload: {
+        credentials: TrezorThpCredentials[];
+    }) => Promise<void> | void;
+    logger?: TrezorDebugLogger;
+};
+declare class TrezorDeviceSession {
+    private readonly transport;
+    private readonly connectionType?;
+    private readonly chunkSize;
+    private readonly coreFactory;
+    private readonly thpOptions?;
+    private core?;
+    private protocol;
+    private thpState?;
+    private thpAppSessionActive;
+    private currentFeatures?;
+    constructor(options: TrezorDeviceSessionOptions);
+    get features(): Record<string, unknown> | undefined;
+    /**
+     * Whether this device speaks THP (v2). THP supports multiple host-managed
+     * application sessions per channel (passphrase sessions); v1 does not — its
+     * passphrase flow is reactive (device-driven `PassphraseRequest`). The
+     * adapter branches on this to decide whether to drive app-session caching.
+     */
+    get isThp(): boolean;
+    getThpState(): TrezorThpState | undefined;
+    initialize(): Promise<Record<string, unknown>>;
+    call(name: string, data?: Record<string, unknown>): Promise<{
+        type: string;
+        message: Record<string, unknown>;
+    }>;
+    private initializeThp;
+    /**
+     * Create a NEW THP application session with a freshly-prompted passphrase
+     * (or empty if the device has no passphrase protection). Returns the new
+     * session id (hex). The session knows nothing about wallet identity (XFP) —
+     * the adapter derives that (via master fingerprint) and owns the
+     * XFP↔sessionId map. Multiple sessions can coexist on one channel.
+     */
+    createThpAppSession(deriveCardano?: boolean): Promise<string>;
+    /**
+     * Switch the active THP session to an existing id (host-side: just sets the
+     * session-id byte in the next message header). The device must still hold
+     * the session — validity is verified by the caller's next real call (an
+     * evicted session surfaces as a Failure/ThpError, the adapter then recreates).
+     */
+    selectThpAppSession(sessionId: string): void;
+    /** Active THP session id (hex), or undefined if none created/selected. */
+    getThpAppSessionId(): string | undefined;
+    private ensureThpApplicationSession;
+    private handleButtonRequest;
+    private handlePinMatrixRequest;
+    private handlePassphraseRequest;
+    private cancelCurrentCall;
+    private log;
+}
+
+export { type TrezorByteTransport, type TrezorCallOptions, TrezorCore, type TrezorCoreFactory, type TrezorCoreLike, type TrezorCoreOptions, type TrezorDebugLogEntry, type TrezorDebugLogLevel, type TrezorDebugLogger, TrezorDeviceSession, TrezorFailureError, type TrezorMessageName, type TrezorMessageResponse, type TrezorPinMatrixRequestPayload, type TrezorThpCallParams, type TrezorThpCredentials, type TrezorThpHandshakeCredentials, type TrezorThpHandshakeInitHandler, type TrezorThpHandshakeInitResponse, type TrezorThpPairingMethod, TrezorThpProtocol, type TrezorThpRawTransport, type TrezorThpSessionOptions, type TrezorThpState, type TrezorTransportProtocol };