@sidhujag/sysweb3-keyring 2.1.11 → 2.1.12

package/esm/keyring-core.js

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _KeyringCore_instances, _KeyringCore_deviceUnlockRetired, _KeyringCore_sessionOwnership, _KeyringCore_createDeviceUnlockControls, _KeyringCore_acceptSessionFrom, _KeyringCore_assertSessionOwner, _KeyringCore_captureSessionGuard, _KeyringCore_replaceSessionBuffers, _KeyringCore_finishUnlock, _KeyringCore_installVaultSession, _KeyringCore_recreateSessionFromVault;
+var _KeyringCore_instances, _KeyringCore_recordAccess, _KeyringCore_recordAccessOwner, _KeyringCore_deviceUnlockRetired, _KeyringCore_sessionOwnership, _KeyringCore_createDeviceUnlockControls, _KeyringCore_capturePublicSessionGuard, _KeyringCore_acceptSessionFrom, _KeyringCore_assertSessionOwner, _KeyringCore_captureSessionGuard, _KeyringCore_replaceSessionBuffers, _KeyringCore_finishUnlock, _KeyringCore_installVaultSession, _KeyringCore_recreateSessionFromVault;
 import ecc from '@bitcoinerlab/secp256k1';
 import { INetworkType, getNetworkConfig, } from '@sidhujag/sysweb3-network';
 import { BIP32Factory } from 'bip32';
@@ -31,10 +31,11 @@ const SLH_DSA_SETUP_SECRET_HEX_LENGTH = 64;
 const SLH_DSA_PARAMETER_SET = 'SLH-DSA-SHA2-128-24';
 import { currentVaultRefusals } from './current-vault-refusal';
 import { isHexString } from './ethers-v6';
-import { assertHardwareOperationCurrent } from './hardware-transaction-authority';
+import { assertHardwareOperationCurrent, captureHardwareTransactionAuthority, } from './hardware-transaction-authority';
 import { initialActiveImportedAccountState, initialActiveLedgerAccountState, initialActiveTrezorAccountState, } from './initial-state';
 import { takeKeyringHostBinding } from './keyring-host';
-import { decryptPrivateRecordBytes, encryptPrivateRecordBytes, privateRecordProfileId, } from './private-records';
+import { decryptPrivateRecordBytes, sealPublicRecordCheckpoint, restorePublicRecordCheckpoint, encryptPrivateRecordBytes, privateRecordProfileId, createPrivateRecordAccess, activePrivateRecordDomainSet, privateRecordDomainSet, privateRecordAccessCanTransfer, transferPrivateRecordAccess, } from './private-records';
+import { capturePublicSessionRequest, capturePublicSessionCheckpoint, capturePublicSessionKey, publicSessionStateDigest, } from './public-session';
 import { getSyscoinSigners } from './signers';
 import { snapshotEvmHdIndex } from './software-hd-account';
 import { decryptCurrentVault, VaultAuthenticationError } from './storage-core';
@@ -160,9 +161,16 @@ export class KeyringCore {
         this.sessionMnemonic = null; // can be a mnemonic or a zprv, can be changed to a zprv when using an imported wallet
         this.privateRecordSessionRevision = 0;
         this.sessionLifetime = new AbortController();
+        this.publicSession = false;
+        this.publicSessionRevision = 0;
+        _KeyringCore_recordAccess.set(this, new Set());
+        _KeyringCore_recordAccessOwner.set(this, Object.freeze({}));
         _KeyringCore_deviceUnlockRetired.set(this, false);
         _KeyringCore_sessionOwnership.set(this, void 0);
-        this.createSyscoinTransactions = () => new SyscoinTransactionsCore(this.getSigner, this.getReadOnlySigner, this.getAccountsState, this.syscoinHardwareSigners, this.capturePsbtSigningContext);
+        this.createSyscoinTransactions = () => new SyscoinTransactionsCore(this.getSigner, this.getReadOnlySigner, this.getAccountsState, this.syscoinHardwareSigners, this.capturePublicWalletContext, this.secretLifetime, () => {
+            if (this.secretLifetime === 'operation' && this.isUnlocked())
+                throw new Error('Prepare PSBT before the secret operation');
+        });
         this.requireLedgerSigner = () => {
             if (!this.ledgerSigner)
                 throw createHardwareSignerUnavailableError('Ledger');
@@ -179,23 +187,25 @@ export class KeyringCore {
                 ? KeyringAccountType.Imported
                 : KeyringAccountType.HDAccount;
         };
-        this.isUnlocked = () => !!this.sessionPassword && !this.sessionPassword.isCleared();
+        this.isUnlocked = () => !!this.sessionPassword &&
+            !this.sessionPassword.isCleared() &&
+            (this.secretLifetime === 'session' ||
+                (!!this.secretOperation?.active && this.secretOperation.working));
+        /** Public authenticated account context is independent of decrypted key availability. */
+        this.hasPublicSession = () => {
+            return this.secretLifetime === 'session'
+                ? this.isUnlocked()
+                : this.publicSession &&
+                    __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").tracker.current ===
+                        __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").token;
+        };
         this.lockWallet = async () => {
-            this.retireSessionLifetime();
-            // Clear secure session data
-            if (this.sessionPassword) {
-                this.sessionPassword.clear();
-                this.sessionPassword = null;
-            }
-            if (this.sessionMnemonic) {
-                this.sessionMnemonic.clear();
-                this.sessionMnemonic = null;
-            }
-            const ownership = __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f");
-            if (ownership.tracker.current === ownership.token) {
-                ownership.tracker.current = undefined;
-                ownership.tracker.epoch++;
-            }
+            this.clearRecordAccess();
+            this.publicSession = false;
+            this.publicSessionRevision++;
+            if (this.secretOperation)
+                this.secretOperation.active = false;
+            this.clearSecretMaterial(false);
             // Clear transaction handlers that may hold HD signers
             if (this.syscoinTransaction) {
                 // Replace with empty object to clear references
@@ -223,26 +233,35 @@ export class KeyringCore {
         };
         /** Retire hardware before preparing a synchronous, one-use session move. */
         this.prepareSessionTransfer = async (targetKeyring, assertCurrent) => {
-            if (!this.isUnlocked()) {
+            const publicOnly = this.secretLifetime === 'operation';
+            if (publicOnly && this.secretOperation)
+                throw new Error('Secret operation is busy');
+            if (publicOnly ? !this.hasPublicSession() : !this.isUnlocked()) {
                 throw new Error('Source keyring must be unlocked to transfer session');
             }
             // Cross-wallet transfers must fail before either keyring's buffers change.
             if (!(targetKeyring instanceof KeyringCore) ||
                 targetKeyring.authority !== this.authority ||
+                targetKeyring.secretLifetime !== this.secretLifetime ||
                 targetKeyring.storage !== this.storage ||
                 targetKeyring.vaultPersistence !== this.vaultPersistence ||
                 __classPrivateFieldGet(targetKeyring, _KeyringCore_sessionOwnership, "f").tracker !== __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").tracker) {
                 throw new Error('Cannot transfer session between different wallet authorities');
             }
-            const sourceGuard = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this);
+            const sourceGuard = publicOnly
+                ? __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this)
+                : __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this);
             const targetRevision = targetKeyring.privateRecordSessionRevision;
             const ledger = this.ledgerSigner;
             const trezor = this.trezorSigner;
             const retirementChecks = [];
             const checkOwnership = () => {
                 sourceGuard();
-                if (!this.isUnlocked() ||
-                    !this.sessionMnemonic ||
+                if ((publicOnly &&
+                    (this.secretOperation || targetKeyring.secretOperation)) ||
+                    (publicOnly
+                        ? !this.hasPublicSession()
+                        : !this.isUnlocked() || !this.sessionMnemonic) ||
                     this.ledgerSigner !== ledger ||
                     this.trezorSigner !== trezor ||
                     __classPrivateFieldGet(targetKeyring, _KeyringCore_sessionOwnership, "f").destroyed ||
@@ -294,12 +313,39 @@ export class KeyringCore {
                     check();
                     if (targetKeyring === this)
                         return;
-                    __classPrivateFieldGet(targetKeyring, _KeyringCore_instances, "m", _KeyringCore_acceptSessionFrom).call(targetKeyring, this);
-                    this.retireSessionLifetime();
+                    if (publicOnly) {
+                        const sourceRecords = [...__classPrivateFieldGet(this, _KeyringCore_recordAccess, "f")].filter((access) => privateRecordAccessCanTransfer(access, __classPrivateFieldGet(this, _KeyringCore_recordAccessOwner, "f")));
+                        const retiringRecords = [...__classPrivateFieldGet(this, _KeyringCore_recordAccess, "f")].filter((access) => !sourceRecords.includes(access));
+                        targetKeyring.clearRecordAccess();
+                        // No facade is delivered until the synchronous authority move is complete.
+                        const targetOwner = {};
+                        const movedRecords = sourceRecords.map((access) => transferPrivateRecordAccess(access, __classPrivateFieldGet(this, _KeyringCore_recordAccessOwner, "f"), __classPrivateFieldGet(targetKeyring, _KeyringCore_recordAccessOwner, "f"), () => {
+                            if (!targetOwner.guard)
+                                throw new Error('Record access transfer is incomplete');
+                            targetOwner.guard();
+                        }));
+                        for (const access of retiringRecords)
+                            access.dispose();
+                        __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f").clear();
+                        this.publicSession = false;
+                        this.publicSessionRevision++;
+                        targetKeyring.publicSession = true;
+                        targetKeyring.publicSessionRevision++;
+                        __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").tracker.current =
+                            __classPrivateFieldGet(targetKeyring, _KeyringCore_sessionOwnership, "f").token;
+                        __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").tracker.epoch++;
+                        targetOwner.guard = __classPrivateFieldGet(targetKeyring, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(targetKeyring);
+                        for (const access of movedRecords)
+                            __classPrivateFieldGet(targetKeyring, _KeyringCore_recordAccess, "f").add(access);
+                    }
+                    else {
+                        __classPrivateFieldGet(targetKeyring, _KeyringCore_instances, "m", _KeyringCore_acceptSessionFrom).call(targetKeyring, this);
+                        this.retireSessionLifetime();
+                        // Move the original SecureBuffers without copying their contents.
+                        this.sessionPassword = null;
+                        this.sessionMnemonic = null;
+                    }
                     __classPrivateFieldSet(this, _KeyringCore_deviceUnlockRetired, true, "f");
-                    // Move the original SecureBuffers without copying their contents.
-                    this.sessionPassword = null;
-                    this.sessionMnemonic = null;
                 },
             });
         };
@@ -350,7 +396,7 @@ export class KeyringCore {
             };
         };
         this.getActiveUtxoAddressAccount = (id, ownedRead) => {
-            const captured = captureOwnedSyscoinRead(ownedRead, this.getAccountsState, this.capturePsbtSigningContext);
+            const captured = captureOwnedSyscoinRead(ownedRead, this.getAccountsState, this.capturePublicWalletContext);
             if (id !== captured.accountId)
                 throw new Error('UTXO account is not active');
             const account = this.getVault().accounts[captured.accountType]?.[id];
@@ -729,8 +775,6 @@ export class KeyringCore {
                 const isLedger = activeAccountType === KeyringAccountType.Ledger;
                 const isTrezor = activeAccountType === KeyringAccountType.Trezor;
                 const isHardwareWallet = isTrezor || isLedger;
-                if (!this.sessionPassword)
-                    throw new Error('Wallet is locked cant proceed with transaction');
                 const activeAccountData = accounts[activeAccountType][activeAccountId];
                 if (!activeAccountData) {
                     throw new Error(`Active account (${activeAccountType}:${activeAccountId}) not found. Account switching may be in progress.`);
@@ -741,11 +785,14 @@ export class KeyringCore {
                 if (isTrezor || activeAccountData.isTrezorWallet)
                     this.requireTrezorSigner();
                 if (isHardwareWallet) {
+                    __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this)();
                     return {
                         address,
                         decryptedPrivateKey: '',
                     };
                 }
+                if (!this.sessionPassword)
+                    throw new Error('Wallet is locked cant proceed with transaction');
                 if (!xprv) {
                     throw new Error(`Private key not found for account ${activeAccountType}:${activeAccountId}. Account may not be fully initialized.`);
                 }
@@ -796,7 +843,40 @@ export class KeyringCore {
                 throw error;
             }
         };
+        this.captureEthereumSigningContext = () => {
+            const { activeAccount } = this.getVault();
+            if (activeAccount.type === KeyringAccountType.Ledger ||
+                activeAccount.type === KeyringAccountType.Trezor)
+                return this.capturePublicWalletContext();
+            return this.capturePsbtSigningContext();
+        };
+        this.capturePublicWalletContext = () => {
+            if (this.secretLifetime === 'session')
+                return this.capturePsbtSigningContext();
+            const publicGuard = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this);
+            const vault = this.getVault();
+            const selected = { ...vault.activeAccount };
+            const account = vault.accounts[selected.type]?.[selected.id];
+            const identity = { address: account?.address, xpub: account?.xpub };
+            const network = { ...vault.activeNetwork };
+            const check = () => {
+                publicGuard();
+                const current = this.getVault(), currentAccount = current.accounts[selected.type]?.[selected.id];
+                if (current.activeAccount.id !== selected.id ||
+                    current.activeAccount.type !== selected.type ||
+                    currentAccount?.address !== identity.address ||
+                    currentAccount?.xpub !== identity.xpub ||
+                    current.activeNetwork.kind !== network.kind ||
+                    current.activeNetwork.chainId !== network.chainId ||
+                    current.activeNetwork.slip44 !== network.slip44 ||
+                    current.activeNetwork.url !== network.url)
+                    throw new Error('Wallet public context changed');
+            };
+            check();
+            return check;
+        };
         this.capturePsbtSigningContext = (bindSessionRevision = true) => {
+            this.assertSecretAccess();
             const session = this.sessionPassword;
             const revision = this.privateRecordSessionRevision;
             const vault = this.getVault();
@@ -1127,6 +1207,7 @@ export class KeyringCore {
         };
         // NEW: Separate session initialization from account creation
         this.initializeSession = async (seedPhrase, password) => {
+            this.assertSecretAccess();
             // Validate inputs first
             if (!BIP84.validateMnemonic(seedPhrase)) {
                 throw new Error('Invalid Seed');
@@ -1232,12 +1313,41 @@ export class KeyringCore {
             }
         };
         this.initializeWalletSecurely = async (seedPhrase, password) => {
-            // Use new separated approach
-            await this.initializeSession(seedPhrase, password);
-            return await this.createFirstAccount();
+            if (this.secretLifetime === 'session') {
+                await this.initializeSession(seedPhrase, password);
+                return await this.createFirstAccount();
+            }
+            if (this.secretOperation)
+                throw new Error('Secret operation is busy');
+            const operation = {
+                active: true,
+                working: true,
+                assertCurrent: () => {
+                    if (!operation.active || this.secretOperation !== operation)
+                        throw new Error('Secret operation cancelled');
+                    __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_assertSessionOwner).call(this);
+                },
+            };
+            this.secretOperation = operation;
+            try {
+                await this.initializeSession(seedPhrase, password);
+                operation.assertCurrent();
+                const result = await this.createFirstAccount();
+                operation.assertCurrent();
+                this.publicSession = true;
+                this.publicSessionRevision++;
+                return result;
+            }
+            finally {
+                operation.active = false;
+                this.clearSecretMaterial(this.publicSession);
+                if (this.secretOperation === operation)
+                    this.secretOperation = undefined;
+            }
         };
         const dependencies = takeKeyringHostBinding(binding);
         this.authority = dependencies.authority;
+        this.secretLifetime = dependencies.secretLifetime;
         __classPrivateFieldSet(this, _KeyringCore_sessionOwnership, {
             tracker: dependencies.sessionOwner,
             token: Symbol(),
@@ -1252,7 +1362,7 @@ export class KeyringCore {
         this.initialTrezorAccountState = initialActiveTrezorAccountState;
         this.initialLedgerAccountState = initialActiveLedgerAccountState;
         this.syscoinTransaction = this.createSyscoinTransactions();
-        this.ethereumTransaction = new EthereumTransactions(this.getNetwork, this.getDecryptedPrivateKey, this.getAccountsState, this.ledgerSigner, this.trezorSigner, this.capturePsbtSigningContext, dependencies.captureEvmSubmission);
+        this.ethereumTransaction = new EthereumTransactions(this.getNetwork, this.getDecryptedPrivateKey, this.getAccountsState, this.ledgerSigner, this.trezorSigner, this.captureEthereumSigningContext, dependencies.captureEvmSubmission);
         if (dependencies.deviceUnlock) {
             const { port, receive } = dependencies.deviceUnlock;
             const readVaultPair = this.storage.readDeviceUnlockVaultPair;
@@ -1273,6 +1383,399 @@ export class KeyringCore {
         // No need to explicitly set active account - it's managed externally
         return account;
     }
+    capturePublicSessionGuard() {
+        return __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this);
+    }
+    assertSecretAccess() {
+        if (this.secretLifetime === 'session')
+            return;
+        const operation = this.secretOperation;
+        if (!operation?.active || !operation.working)
+            throw new Error('A secret operation is required');
+        operation.assertCurrent();
+    }
+    clearSecretMaterial(keepPublicSession) {
+        this.retireSessionLifetime();
+        this.sessionPassword?.clear();
+        this.sessionPassword = null;
+        this.sessionMnemonic?.clear();
+        this.sessionMnemonic = null;
+        const ownership = __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f");
+        if (!keepPublicSession && ownership.tracker.current === ownership.token) {
+            ownership.tracker.current = undefined;
+            ownership.tracker.epoch++;
+        }
+    }
+    /** The SDK returns only the work result, never its credential or secret lease. */
+    async withSecretOperation(credential, options, work) {
+        if (this.secretLifetime !== 'operation')
+            throw new Error('Operation secret policy is required');
+        if (this.secretOperation)
+            throw new Error('Secret operation is busy');
+        if (!credential ||
+            typeof credential.withSecret !== 'function' ||
+            typeof work !== 'function' ||
+            !options ||
+            typeof options.assertCurrent !== 'function' ||
+            !options.signal ||
+            typeof options.signal.addEventListener !== 'function')
+            throw new TypeError('Invalid secret operation');
+        let publicGuard = this.hasPublicSession()
+            ? __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this)
+            : undefined;
+        const initialGuard = publicGuard ? undefined : __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this);
+        const authority = captureHardwareTransactionAuthority(options);
+        const withSecret = credential.withSecret.bind(credential);
+        if (this.secretOperation)
+            throw new Error('Secret operation is busy');
+        const operation = {
+            active: true,
+            working: false,
+            assertCurrent: () => {
+                if (!operation.active ||
+                    this.secretOperation !== operation ||
+                    authority.signal.aborted)
+                    throw new Error('Secret operation cancelled');
+                (publicGuard ?? initialGuard)();
+                authority.assertCurrent();
+                (publicGuard ?? initialGuard)();
+            },
+        };
+        this.secretOperation = operation;
+        let entered = false, completed = false, succeeded = false, createdPublicRevision, result;
+        let pending;
+        const retire = () => {
+            operation.active = false;
+            if (this.secretOperation === operation)
+                this.clearSecretMaterial(this.hasPublicSession());
+        };
+        authority.signal.addEventListener('abort', retire, { once: true });
+        try {
+            operation.assertCurrent();
+            await withSecret(operation.assertCurrent, (secret) => {
+                if (entered) {
+                    const rejected = Promise.reject(new Error('Secret credential was already consumed'));
+                    void rejected.catch(() => undefined);
+                    return rejected;
+                }
+                entered = true;
+                pending = (async () => {
+                    try {
+                        operation.assertCurrent();
+                        if (typeof secret !== 'string' || !secret)
+                            throw new TypeError('Invalid secret credential');
+                        const authenticated = await this.unlockSession(secret);
+                        if (!operation.active ||
+                            this.secretOperation !== operation ||
+                            authority.signal.aborted)
+                            throw new Error('Secret operation cancelled');
+                        authority.assertCurrent();
+                        if (!authenticated.canLogin)
+                            throw new Error('Invalid secret credential');
+                        if (!publicGuard) {
+                            __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_assertSessionOwner).call(this);
+                            if (!this.sessionPassword || this.sessionPassword.isCleared())
+                                throw new Error('Secret operation cancelled');
+                            this.publicSession = true;
+                            createdPublicRevision = ++this.publicSessionRevision;
+                            publicGuard = this.capturePublicSessionGuard();
+                        }
+                        operation.assertCurrent();
+                        operation.working = true;
+                        result = await work(secret);
+                        operation.assertCurrent();
+                        completed = true;
+                    }
+                    finally {
+                        operation.working = false;
+                        if (this.secretOperation === operation)
+                            this.clearSecretMaterial(this.hasPublicSession());
+                    }
+                })();
+                void pending.catch(() => undefined);
+                return pending;
+            });
+            if (pending)
+                await pending;
+            operation.assertCurrent();
+            if (!entered || !completed)
+                throw new Error('Secret credential was not consumed');
+            succeeded = true;
+            return result;
+        }
+        finally {
+            if (!succeeded &&
+                createdPublicRevision !== undefined &&
+                this.publicSessionRevision === createdPublicRevision &&
+                this.hasPublicSession()) {
+                this.clearRecordAccess();
+                this.publicSession = false;
+                this.publicSessionRevision++;
+            }
+            retire();
+            authority.signal.removeEventListener('abort', retire);
+            if (this.secretOperation === operation)
+                this.secretOperation = undefined;
+        }
+    }
+    /** Seal a host-validated immutable public manifest from a currently authorized secret session. */
+    async createPublicSessionCheckpoint(input, wrappingKey, assertCurrent) {
+        this.assertSecretAccess();
+        const request = capturePublicSessionRequest(input);
+        const session = this.privateRecordSession();
+        const password = this.sessionPassword;
+        const readPair = this.storage.readDeviceUnlockVaultPair;
+        if (!password || typeof readPair !== 'function') {
+            session.secret.fill(0);
+            throw new Error('Public session requires atomic wallet storage');
+        }
+        const check = () => {
+            this.assertSecretAccess();
+            session.assertCurrent();
+            assertHardwareOperationCurrent(assertCurrent);
+            this.assertSecretAccess();
+            session.assertCurrent();
+        };
+        let wrappingSecret, vaultKey, passwordKey;
+        try {
+            wrappingSecret = capturePublicSessionKey(wrappingKey);
+            check();
+            const pair = await readCurrentVaultPair(readPair.bind(this.storage));
+            check();
+            if (!pair)
+                throw new Error('Public session wallet is unavailable');
+            vaultKey = this.hexToBytes(password.toString());
+            let difference = vaultKey.length ^ wrappingSecret.length;
+            for (let index = 0; index < wrappingSecret.length; index++)
+                difference |= wrappingSecret[index] ^ (vaultKey[index] ?? 0);
+            if (difference === 0)
+                throw new Error('Public session key must be independent of the vault key');
+            // Catch direct reuse of a 32-byte UTF-8 wallet password as well. Random
+            // wrapping bytes normally fail strict decoding and need no extra KDF.
+            // This detects known credential reuse, not arbitrary key provenance.
+            let candidatePassword;
+            try {
+                candidatePassword = new TextDecoder('utf-8', {
+                    fatal: true,
+                    ignoreBOM: true,
+                }).decode(wrappingSecret);
+            }
+            catch {
+                // A binary public-view key is expected and does not need decoding.
+            }
+            if (candidatePassword !== undefined) {
+                passwordKey = this.hexToBytes(await this.deriveStoredSessionKey(candidatePassword, {
+                    salt: pair.salt,
+                }));
+                check();
+                let passwordDifference = vaultKey.length ^ passwordKey.length;
+                for (let index = 0; index < passwordKey.length; index++)
+                    passwordDifference |= passwordKey[index] ^ (vaultKey[index] ?? 0);
+                passwordKey.fill(0);
+                passwordKey = undefined;
+                if (passwordDifference === 0)
+                    throw new Error('Public session key must be independent of the vault password');
+            }
+            vaultKey.fill(0);
+            vaultKey = undefined;
+            // A checkpoint must never attest a different pair using an old live root.
+            const payload = await decryptCurrentVault(pair.vault, password.toString());
+            check();
+            if (!payload ||
+                typeof payload !== 'object' ||
+                Object.getOwnPropertyDescriptor(payload, 'mnemonic')?.value?.normalize('NFKD') !== new TextDecoder().decode(session.secret))
+                throw new Error('Public session wallet changed');
+            const digest = await publicSessionStateDigest(request.publicState, check);
+            const checkpoint = await sealPublicRecordCheckpoint(session.secret, wrappingSecret, {
+                walletBindingId: request.walletBindingId,
+                pairFingerprint: pair.pairFingerprint,
+                stateDigest: digest,
+                domains: request.recordDomains,
+            }, check);
+            const current = await readCurrentVaultPair(readPair.bind(this.storage));
+            check();
+            if (!current ||
+                current.vault !== pair.vault ||
+                current.salt !== pair.salt ||
+                current.pairFingerprint !== pair.pairFingerprint)
+                throw new Error('Public session wallet changed');
+            return checkpoint;
+        }
+        finally {
+            session.secret.fill(0);
+            wrappingSecret?.fill(0);
+            vaultKey?.fill(0);
+            passwordKey?.fill(0);
+            request.publicState.fill(0);
+        }
+    }
+    /** Restore only authenticated public state and record keys. Never decrypts the vault. */
+    async restorePublicSession(credential, input, options, work) {
+        if (this.secretLifetime !== 'operation')
+            throw new Error('Operation secret policy is required');
+        // Capture cancellation before any caller-controlled property or guard runs.
+        const initialGuard = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this);
+        initialGuard();
+        if (this.secretOperation || this.hasPublicSession() || this.isUnlocked())
+            throw new Error('Public session restore requires a locked wallet');
+        if (!credential ||
+            typeof credential.withKey !== 'function' ||
+            typeof work !== 'function')
+            throw new TypeError('Invalid public session restore');
+        const readPair = this.storage.readDeviceUnlockVaultPair;
+        if (typeof readPair !== 'function')
+            throw new Error('Public session requires atomic wallet storage');
+        const withKey = credential.withKey.bind(credential);
+        const request = capturePublicSessionRequest(input);
+        const checkpoint = capturePublicSessionCheckpoint(input);
+        const authority = captureHardwareTransactionAuthority(options);
+        initialGuard();
+        // A reentrant host guard may have admitted a different operation.
+        if (this.secretOperation || this.hasPublicSession() || this.isUnlocked())
+            throw new Error('Public session restore requires a locked wallet');
+        let publicGuard;
+        const operation = {
+            active: true,
+            working: false,
+            assertCurrent: () => {
+                if (!operation.active ||
+                    this.secretOperation !== operation ||
+                    authority.signal.aborted)
+                    throw new Error('Public session restore cancelled');
+                (publicGuard ?? initialGuard)();
+                authority.assertCurrent();
+                if (!operation.active ||
+                    this.secretOperation !== operation ||
+                    authority.signal.aborted)
+                    throw new Error('Public session restore cancelled');
+                (publicGuard ?? initialGuard)();
+            },
+        };
+        const check = operation.assertCurrent;
+        let restored;
+        let succeeded = false, entered = false, completed = false;
+        let pending, result;
+        const retire = () => {
+            operation.active = false;
+            if (this.secretOperation !== operation)
+                return;
+            this.clearRecordAccess();
+            this.publicSession = false;
+            this.publicSessionRevision++;
+            this.clearSecretMaterial(false);
+        };
+        this.secretOperation = operation;
+        authority.signal.addEventListener('abort', retire, { once: true });
+        try {
+            check();
+            const pair = await readCurrentVaultPair(readPair.bind(this.storage));
+            check();
+            if (!pair)
+                throw new Error('Public session wallet is unavailable');
+            const checkPair = async () => {
+                const current = await readCurrentVaultPair(readPair.bind(this.storage));
+                check();
+                if (!current ||
+                    current.vault !== pair.vault ||
+                    current.salt !== pair.salt ||
+                    current.pairFingerprint !== pair.pairFingerprint)
+                    throw new Error('Public session wallet changed');
+            };
+            const digest = await publicSessionStateDigest(request.publicState, check);
+            await withKey(check, (key) => {
+                if (entered) {
+                    const rejected = Promise.reject(new Error('Public session credential was already consumed'));
+                    void rejected.catch(() => undefined);
+                    return rejected;
+                }
+                entered = true;
+                pending = (async () => {
+                    let wrappingSecret;
+                    try {
+                        wrappingSecret = capturePublicSessionKey(key);
+                        check();
+                        restored = await restorePublicRecordCheckpoint(wrappingSecret, checkpoint, {
+                            walletBindingId: request.walletBindingId,
+                            pairFingerprint: pair.pairFingerprint,
+                            stateDigest: digest,
+                            domains: request.recordDomains,
+                        }, () => (publicGuard ? publicGuard() : check()), __classPrivateFieldGet(this, _KeyringCore_recordAccessOwner, "f"));
+                        wrappingSecret.fill(0);
+                        wrappingSecret = undefined;
+                        await checkPair();
+                        this.clearRecordAccess();
+                        this.publicSession = true;
+                        this.publicSessionRevision++;
+                        __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").tracker.current =
+                            __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").token;
+                        __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").tracker.epoch++;
+                        publicGuard = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this);
+                        __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f").add(restored);
+                        check();
+                        // Recreate only the public transaction wrapper retired by lockWallet.
+                        this.syscoinTransaction = this.createSyscoinTransactions();
+                        result = await work(request.publicState);
+                        check();
+                        await checkPair();
+                        completed = true;
+                    }
+                    finally {
+                        wrappingSecret?.fill(0);
+                    }
+                })();
+                void pending.catch(() => undefined);
+                return pending;
+            });
+            if (pending)
+                await pending;
+            check();
+            if (!entered || !completed)
+                throw new Error('Public session credential was not consumed');
+            succeeded = true;
+            return result;
+        }
+        finally {
+            authority.signal.removeEventListener('abort', retire);
+            request.publicState.fill(0);
+            if (!succeeded) {
+                restored?.dispose();
+                retire();
+            }
+            else {
+                operation.active = false;
+                this.clearSecretMaterial(true);
+            }
+            if (this.secretOperation === operation)
+                this.secretOperation = undefined;
+        }
+    }
+    async unlock(password) {
+        if (this.secretLifetime === 'session')
+            return this.unlockSession(password);
+        if (this.secretOperation)
+            throw new Error('Secret operation is busy');
+        const operation = {
+            active: true,
+            working: false,
+            assertCurrent: __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this),
+        };
+        this.secretOperation = operation;
+        try {
+            const result = await this.unlockSession(password);
+            if (result.canLogin) {
+                this.clearRecordAccess();
+                this.publicSession = true;
+                this.publicSessionRevision++;
+            }
+            return result;
+        }
+        finally {
+            operation.active = false;
+            this.clearSecretMaterial(this.publicSession);
+            if (this.secretOperation === operation)
+                this.secretOperation = undefined;
+        }
+    }
     /** Capture wallet-session authority without binding an account or network. */
     captureUnlockedSessionGuard() {
         const assertOwner = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this);
@@ -1294,7 +1797,7 @@ export class KeyringCore {
      * Storage, platform and session restoration failures reject so callers do
      * not charge a failed password attempt for an operational error.
      */
-    async unlock(password) {
+    async unlockSession(password) {
         let assertCurrent = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this);
         let authenticated = false;
         try {
@@ -1513,6 +2016,51 @@ export class KeyringCore {
             throw new Error('Invalid private record root');
         return { secret: new TextEncoder().encode(root), assertCurrent };
     }
+    clearRecordAccess() {
+        for (const access of __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f"))
+            access.dispose();
+        __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f").clear();
+    }
+    /** Public transaction records may outlive a signer without retaining the spending root. */
+    async createPrivateRecordAccess(domains, options) {
+        this.assertSecretAccess();
+        const session = this.privateRecordSession();
+        const publicGuard = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this);
+        for (const previous of __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f")) {
+            if (activePrivateRecordDomainSet(previous, __classPrivateFieldGet(this, _KeyringCore_recordAccessOwner, "f")) === null)
+                __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f").delete(previous);
+        }
+        let access;
+        try {
+            access = await createPrivateRecordAccess(session.secret, domains, options, publicGuard, __classPrivateFieldGet(this, _KeyringCore_recordAccessOwner, "f"));
+            session.assertCurrent();
+            publicGuard();
+            __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f").add(access);
+            return access;
+        }
+        catch (error) {
+            access?.dispose();
+            throw error;
+        }
+        finally {
+            session.secret.fill(0);
+        }
+    }
+    /** Retrieve only an exact domain set already derived under a secret operation. Never unlocks or derives. */
+    getPrivateRecordAccess(domains) {
+        const guard = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_capturePublicSessionGuard).call(this);
+        const domainSet = privateRecordDomainSet(domains);
+        guard();
+        for (const access of __classPrivateFieldGet(this, _KeyringCore_recordAccess, "f")) {
+            if (privateRecordAccessCanTransfer(access, __classPrivateFieldGet(this, _KeyringCore_recordAccessOwner, "f")) &&
+                activePrivateRecordDomainSet(access, __classPrivateFieldGet(this, _KeyringCore_recordAccessOwner, "f")) ===
+                    domainSet) {
+                guard();
+                return access;
+            }
+        }
+        throw new Error('Record access is not initialized for these domains');
+    }
     /** Stable local profile identifier; never an account address or a key. */
     async getPrivateRecordProfileId() {
         const session = this.privateRecordSession();
@@ -2475,6 +3023,7 @@ export class KeyringCore {
     }
     // Helper methods for secure buffer operations
     getSessionPasswordString() {
+        this.assertSecretAccess();
         if (!this.sessionPassword || this.sessionPassword.isCleared()) {
             throw new Error('Session password not available');
         }
@@ -2483,6 +3032,7 @@ export class KeyringCore {
         return this.sessionPassword.toString();
     }
     getSessionMnemonicString() {
+        this.assertSecretAccess();
         if (!this.sessionMnemonic || this.sessionMnemonic.isCleared()) {
             throw new Error('Session mnemonic not available');
         }
@@ -2595,7 +3145,7 @@ export class KeyringCore {
         this.syscoinTransaction = {};
     }
 }
-_KeyringCore_deviceUnlockRetired = new WeakMap(), _KeyringCore_sessionOwnership = new WeakMap(), _KeyringCore_instances = new WeakSet(), _KeyringCore_createDeviceUnlockControls = function _KeyringCore_createDeviceUnlockControls(port, readVaultPair) {
+_KeyringCore_recordAccess = new WeakMap(), _KeyringCore_recordAccessOwner = new WeakMap(), _KeyringCore_deviceUnlockRetired = new WeakMap(), _KeyringCore_sessionOwnership = new WeakMap(), _KeyringCore_instances = new WeakSet(), _KeyringCore_createDeviceUnlockControls = function _KeyringCore_createDeviceUnlockControls(port, readVaultPair) {
     const readPair = () => readCurrentVaultPair(readVaultPair);
     let pending = false;
     const run = async (request, assertCurrent) => {
@@ -2686,7 +3236,13 @@ _KeyringCore_deviceUnlockRetired = new WeakMap(), _KeyringCore_sessionOwnership
             else {
                 if (__classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_finishUnlock).call(this).needsAccountCreation)
                     return false;
+                this.clearRecordAccess();
                 __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_installVaultSession).call(this, mnemonic, keyHex, check);
+                if (this.secretLifetime === 'operation') {
+                    this.publicSession = true;
+                    this.publicSessionRevision++;
+                    this.clearSecretMaterial(true);
+                }
             }
             return true;
         }
@@ -2704,6 +3260,23 @@ _KeyringCore_deviceUnlockRetired = new WeakMap(), _KeyringCore_sessionOwnership
         },
         resume: (assertCurrent) => run(null, assertCurrent),
     });
+}, _KeyringCore_capturePublicSessionGuard = function _KeyringCore_capturePublicSessionGuard() {
+    const assertOwner = __classPrivateFieldGet(this, _KeyringCore_instances, "m", _KeyringCore_captureSessionGuard).call(this);
+    const revision = this.publicSessionRevision;
+    const check = () => {
+        if (this.secretLifetime === 'session') {
+            assertOwner();
+            if (!this.sessionPassword || this.sessionPassword.isCleared())
+                throw new Error('Wallet unlock session changed');
+        }
+        else if (!this.publicSession ||
+            this.publicSessionRevision !== revision ||
+            __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").tracker.current !== __classPrivateFieldGet(this, _KeyringCore_sessionOwnership, "f").token) {
+            throw new Error('Wallet public session changed');
+        }
+    };
+    check();
+    return check;
 }, _KeyringCore_acceptSessionFrom = function _KeyringCore_acceptSessionFrom(source) {
     if (source.authority !== this.authority ||
         source.storage !== this.storage ||