@sidhujag/sysweb3-keyring 2.1.1 → 2.1.3

package/types/keyring-core.d.ts

@@ -15,7 +15,32 @@ export interface KeyringStoragePort extends VaultStoragePort {
     deleteItem(key: string): Promise<void>;
     /** Legacy adapter capability; fixed native hosts can omit it. */
     setClient?(client: any): void;
+    /** Atomically read this authority's current encrypted vault and salt. */
+    readDeviceUnlockVaultPair?(): Promise<DeviceUnlockVaultPair | null>;
 }
+export type DeviceUnlockVaultPair = Readonly<{
+    vault: string;
+    keys: unknown;
+    pairFingerprint: string;
+}>;
+export type DeviceUnlockCredential = Readonly<{
+    pairFingerprint: string;
+    key: Uint8Array;
+}>;
+/** Only a trusted software host may supply this protected credential I/O. */
+export type DeviceUnlockPort = Readonly<{
+    /** Transfer ownership of the returned key bytes to the SDK. */
+    readCredential(pairFingerprint: string): Promise<DeviceUnlockCredential | null>;
+    /**
+     * Consume the bytes and check the guard before saving. The SDK clears the
+     * bytes on settlement. Publish enrollment only after issue returns true.
+     */
+    writeCredential(credential: DeviceUnlockCredential, assertCurrent: () => void): Promise<void>;
+}>;
+export type DeviceUnlockControls = Readonly<{
+    issue(password: string, assertCurrent: () => void): Promise<boolean>;
+    resume(assertCurrent: () => void): Promise<boolean>;
+}>;
 /** Only the device capabilities consumed by the wallet authority. */
 export interface KeyringLedgerSigner {
     destroy: LedgerKeyring['destroy'];
@@ -24,6 +49,10 @@ export interface KeyringLedgerSigner {
     verifyUtxoAddress: LedgerKeyring['verifyUtxoAddress'];
 }
 export type KeyringTrezorSigner = Pick<TrezorKeyring, 'destroy' | 'getAccountInfo' | 'getPublicKey' | 'signTypedData' | 'signMessage' | 'signEthTransaction' | 'verifyUtxoAddress'>;
+type SessionOwner = {
+    current?: symbol;
+    epoch: number;
+};
 export interface KeyringCoreDependencies<TLedger extends KeyringLedgerSigner | undefined, TTrezor extends KeyringTrezorSigner | undefined> {
     /** Immutable identity shared only by keyrings in the same wallet authority. */
     authority: object;
@@ -36,6 +65,12 @@ export interface KeyringCoreDependencies<TLedger extends KeyringLedgerSigner | u
     syscoinHardwareSigners?: ISyscoinHardwareSigners;
     /** Trusted host lifecycle, captured before each locally signed EVM submission. */
     captureEvmSubmission?: CaptureEvmSubmission;
+    /** Shared only by software keyrings of the same opted-in host. */
+    sessionOwner?: SessionOwner;
+    deviceUnlock?: {
+        port: DeviceUnlockPort;
+        receive(controls: DeviceUnlockControls): void;
+    };
 }
 export interface ISysAccount {
     address: string;
@@ -57,6 +92,7 @@ declare class SecureBuffer {
     isCleared(): boolean;
 }
 export declare class KeyringCore<TLedger extends KeyringLedgerSigner | undefined = KeyringLedgerSigner | undefined, TTrezor extends KeyringTrezorSigner | undefined = KeyringTrezorSigner | undefined> {
+    #private;
     trezorSigner: TTrezor;
     ledgerSigner: TLedger;
     initialTrezorAccountState: IKeyringAccountState;
@@ -86,9 +122,7 @@ export declare class KeyringCore<TLedger extends KeyringLedgerSigner | undefined
     isUnlocked: () => boolean;
     lockWallet: () => Promise<void>;
     transferSessionTo: (targetKeyring: Pick<KeyringCore, "receiveSessionOwnership">) => void;
-    private acceptSessionFrom;
     receiveSessionOwnership: (sessionPassword: SecureBuffer, sessionMnemonic: SecureBuffer) => void;
-    private replaceSessionBuffers;
     addNewAccount: (label?: string) => Promise<IKeyringAccountState>;
     createSmartAccount: ({ address, deriveAccount, label, metadata, }: ICreateSmartAccountParams) => Promise<IKeyringAccountState>;
     /**
@@ -228,7 +262,6 @@ export declare class KeyringCore<TLedger extends KeyringLedgerSigner | undefined
     private setDerivedWeb3Accounts;
     private setSignerEVM;
     private clearTemporaryLocalKeys;
-    private recreateSessionFromVault;
     private _getPrivateKeyAccountInfos;
     /**
      * Common method to decrypt mnemonic from session

package/types/keyring-manager.d.ts

@@ -2,15 +2,27 @@ import { HardwareWalletManager } from './hardware-wallet-manager';
 import { KeyringCore } from './keyring-core';
 import { LedgerKeyring } from './ledger';
 import { TrezorKeyring } from './trezor';
+import type { DeviceUnlockControls, DeviceUnlockPort, KeyringStoragePort } from './keyring-core';
 import type { LedgerHost } from './ledger/host-types';
 import type { CaptureEvmSubmission } from './transactions/evm-submission';
 import type { IKeyringManager } from './types';
 export type { ISysAccount } from './keyring-core';
+export type { DeviceUnlockControls, DeviceUnlockPort, DeviceUnlockVaultPair, KeyringStoragePort, } from './keyring-core';
+declare const keyringManagerHostBrand: unique symbol;
+/** Opaque identity for one explicitly configured browser wallet authority. */
+export interface KeyringManagerHost {
+    readonly [keyringManagerHostBrand]: true;
+}
+/** Create once for a fixed wallet store and share across replacement managers. */
+export declare function createKeyringManagerHost(storage: KeyringStoragePort, deviceUnlock: DeviceUnlockPort): KeyringManagerHost;
+export type KeyringManagerOptions = {
+    captureEvmSubmission?: CaptureEvmSubmission;
+    host?: KeyringManagerHost;
+    receiveDeviceUnlock?(controls: DeviceUnlockControls): void;
+};
 /** Existing browser entry. Native/software hosts must use the software entry. */
 export declare class KeyringManager extends KeyringCore<LedgerKeyring, TrezorKeyring> implements IKeyringManager {
-    constructor(sharedHardwareWalletManager?: HardwareWalletManager, ledgerHost?: LedgerHost, options?: {
-        captureEvmSubmission?: CaptureEvmSubmission;
-    });
+    constructor(sharedHardwareWalletManager?: HardwareWalletManager, ledgerHost?: LedgerHost, options?: KeyringManagerOptions);
     static createInitialized(seed: string, password: string, vaultStateGetter: () => any, options?: {
         captureEvmSubmission?: CaptureEvmSubmission;
     }): Promise<KeyringManager>;

package/types/ledger/dmk-host.d.ts

@@ -0,0 +1,7 @@
+import { type LedgerEvmConfig, type LedgerHost } from './host-types';
+export interface LedgerDmkHost extends LedgerHost {
+    /** Start before enumerating. The returned capability is single use. */
+    beginDeviceSelection(signal?: AbortSignal): (candidate: object) => Promise<void>;
+}
+/** Shared implementation; the default browser host supplies its own transport. */
+export declare function createLedgerHostForDmk(candidate: object, config: LedgerEvmConfig, requireDeviceSelection?: boolean): LedgerDmkHost;

package/types/ledger/dmk-selected-host.d.ts

@@ -0,0 +1,7 @@
+import { type LedgerDmkHost } from './dmk-host';
+import type { LedgerEvmConfig } from './host-types';
+/** A platform-owned transport and explicit user selection are required. */
+export declare function createSelectedLedgerDmkHost(config: LedgerEvmConfig & {
+    dmk: object;
+}): LedgerDmkHost;
+export type { LedgerDmkHost } from './dmk-host';

package/types/ledger/dmk-session.d.ts

@@ -30,8 +30,9 @@ export interface LedgerDmkOperation {
 /** One owner and one semantic operation at a time, across EVM and UTXO apps. */
 export declare class LedgerDmkSession {
     readonly dmk: DeviceManagementKit;
+    private requireDeviceSelection;
     private generation;
-    private sessionId;
+    private connection;
     private queue;
     private activeCancel;
     private activeAbort;
@@ -39,17 +40,24 @@ export declare class LedgerDmkSession {
     private stateSubscription;
     private connectionAttempt;
     private connectionAbort;
+    private deviceSelection;
     private readonly invalidationListeners;
-    constructor(dmk: DeviceManagementKit);
+    constructor(dmk: DeviceManagementKit, requireDeviceSelection?: boolean);
+    private get readyConnection();
     getStatus(): {
         connected: boolean;
     };
     onInvalidated(listener: () => void): () => void;
     private invalidate;
+    /** The platform passes one candidate from its own current DMK picker. */
+    beginDeviceSelection(signal?: AbortSignal): (candidate: object) => Promise<void>;
     /** Device selection belongs to the visible host, never to a dapp request. */
     connect(request?: {
         useGrantedDevices?: boolean;
     }, options?: LedgerOperationOptions): Promise<void>;
+    private connectionBusy;
+    private startConnection;
+    private discoverDevice;
     private connectDevice;
     /** Cancel revokes the result and closes I/O; it cannot undo on-device approval. */
     disconnect(): Promise<void>;

package/types/ledger-host.d.ts

@@ -1,7 +1,11 @@
-import type { LedgerHost, LedgerEvmConfig } from './ledger/host-types';
+import { type LedgerDmkHost } from './ledger/dmk-host';
+import type { LedgerEvmConfig } from './ledger/host-types';
 export interface LedgerDmkHostConfig extends LedgerEvmConfig {
     /** Platform-owned DMK, allowing a future host to register its own transports. */
     dmk?: object;
+    /** Disable automatic discovery until the platform selects a device. */
+    requireDeviceSelection?: boolean;
 }
-export declare function createLedgerDmkHost(config?: LedgerDmkHostConfig): LedgerHost;
+export declare function createLedgerDmkHost(config?: LedgerDmkHostConfig): LedgerDmkHost;
+export type { LedgerDmkHost } from './ledger/dmk-host';
 export type { LedgerEvmConfig, LedgerBlindSigningIntent, LedgerHost, LedgerEvmHost, LedgerUtxoHost, LedgerUtxoAccount, LedgerPartialSignature, LedgerTypedData, LedgerOperationOptions, LedgerProgress, } from './ledger/host-types';

package/types/software.d.ts

@@ -1,6 +1,6 @@
 /** Software-only entry: explicit host storage, no browser/device initialization. */
 import { KeyringCore } from './keyring-core';
-import type { KeyringStoragePort } from './keyring-core';
+import type { DeviceUnlockControls, DeviceUnlockPort, KeyringStoragePort } from './keyring-core';
 import type { EncryptedEvmHdRuntimeAccount, EvmHdRuntimeAccountOptions, EvmHdRuntimeAccountRequest } from './software-hd-account';
 import type { CaptureEvmSubmission } from './transactions/evm-submission';
 import type { PreparedEvmSigningOptions, PreparedSoftwareEvmSigningRequest, SignedPreparedEvmTransaction } from './transactions/prepared-evm';
@@ -12,9 +12,10 @@ export interface SoftwareKeyringHost {
 /** Create once per wallet authority, then share with its per-network keyrings. */
 export declare const createSoftwareKeyringHost: (storage: KeyringStoragePort, options?: {
     captureEvmSubmission?: CaptureEvmSubmission;
+    deviceUnlock?: DeviceUnlockPort;
 }) => SoftwareKeyringHost;
 export declare class SoftwareKeyring extends KeyringCore<undefined, undefined> {
-    constructor(host: SoftwareKeyringHost);
+    constructor(host: SoftwareKeyringHost, receiveDeviceUnlock?: (controls: DeviceUnlockControls) => void);
     /**
      * Derive a fixed-path Ethereum HD runtime account without network or storage
      * writes. The returned password-encrypted xprv is internal runtime state,
@@ -36,7 +37,7 @@ export declare class SoftwareKeyring extends KeyringCore<undefined, undefined> {
 export { KeyringAccountType } from './types';
 export { INetworkType } from '@sidhujag/sysweb3-network';
 export type { INetwork } from '@sidhujag/sysweb3-network';
-export type { KeyringStoragePort } from './keyring-core';
+export type { DeviceUnlockControls, DeviceUnlockCredential, DeviceUnlockPort, DeviceUnlockVaultPair, KeyringStoragePort, } from './keyring-core';
 export type { IKeyringAccountState } from './types';
 export type { PreparedEvmTransaction, PreparedEvmSigningOptions, PreparedSoftwareEvmSigningRequest, SignedPreparedEvmTransaction, } from './transactions/prepared-evm';
 export type { EncryptedEvmHdRuntimeAccount, EvmHdRuntimeAccountOptions, EvmHdRuntimeAccountRequest, } from './software-hd-account';

package/types/storage-core.d.ts

@@ -8,13 +8,15 @@ export interface VaultStoragePort {
 export interface VaultPersistence {
     setEncryptedVault(decryptedVault: any, pwd: string, freshVaultKeys?: {
         salt: string;
-    }): Promise<void>;
+    }, assertCurrent?: () => void): Promise<void>;
     getDecryptedVault(pwd: string, legacyPassword?: string): Promise<any>;
 }
 export declare class VaultAuthenticationError extends Error {
     readonly code = "INVALID_PASSWORD";
     constructor();
 }
+/** Authenticate a captured current-format vault. This path has no CBC fallback. */
+export declare const decryptCurrentVault: (vault: string, key: string) => Promise<unknown>;
 /**
  * Create once per wallet authority and share across its network keyrings.
  * The host owns storage durability and cross-context atomic creation.

package/types/storage.d.ts

@@ -1,5 +1,5 @@
 export declare const setEncryptedVault: (decryptedVault: any, pwd: string, freshVaultKeys?: {
     salt: string;
-}) => Promise<void>;
+}, assertCurrent?: () => void) => Promise<void>;
 export declare const getDecryptedVault: (pwd: string, legacyPassword?: string) => Promise<any>;
 export { VaultAuthenticationError } from './storage-core';

package/types/transactions/evm-cancellation.d.ts

@@ -0,0 +1,10 @@
+import type { planEvmCancellationFees } from '../evm-fees';
+/** A host supplies the authenticated original identity and the captured fee plan. */
+export type EvmCancellationEnvelopeIntent = Readonly<{
+    payer: string;
+    chainId: number | string;
+    nonce: number | string;
+    feePlan: ReturnType<typeof planEvmCancellationFees>;
+}>;
+/** Checks the exact unsigned bytes. Original eligibility and approval remain host checks. */
+export declare function assertEvmCancellationEnvelope(unsigned: string, { payer, chainId, nonce, feePlan }: EvmCancellationEnvelopeIntent): void;

package/types/transactions/evm-submission.d.ts

@@ -1,3 +1,4 @@
+import { Transaction } from 'ethers/transaction';
 export type EvmSubmissionContext = Readonly<{
     account: Readonly<{
         id: number;
@@ -44,5 +45,7 @@ export declare function evmSubmissionFailure(error: unknown): Readonly<{
 }>;
 /** Preserve local evidence when an existing public API wraps its Error object. */
 export declare function copyEvmSubmissionFailure(source: unknown, target: Error): void;
+/** Compare signed wire bytes with the complete envelope captured before signing. */
+export declare function assertSignedEvmTransactionMatches(rawTransaction: string, expectedUnsignedTransaction: string, expectedFrom?: string): Transaction;
 /** The sole local-signature dispatch boundary. No nonce/fee selection or retry. */
-export declare function submitSignedEvmTransaction<T>(rawTransaction: string, broadcast: (rawTransaction: string) => Promise<T>, boundary?: EvmSubmissionBoundary, beforeBroadcast?: () => void): Promise<T>;
+export declare function submitSignedEvmTransaction<T>(rawTransaction: string, broadcast: (rawTransaction: string) => Promise<T>, boundary?: EvmSubmissionBoundary, beforeBroadcast?: () => void, expectedUnsignedTransaction?: string): Promise<T>;