chore(wip): salvage round-2 work in progress for #1702

Co-Authored-By: Claude <noreply@anthropic.com>

Author: MichaelTaylor3d

Cargo.toml

@@ -29,6 +29,8 @@ chia-protocol = "0.26"
 chia-puzzle-types = "0.26"
 chia-wallet-sdk = { version = "0.30", features = ["chip-0035"] }
 clvmr = "0.14"
+# Asset ids and puzzle hashes are rendered as lowercase hex in a summary line.
+hex = "0.4"
 thiserror = "2"
 async-trait = "0.1"
 serde = { version = "1", features = ["derive"] }

src/error.rs

@@ -38,6 +38,18 @@ pub enum AccountError {
     #[error("spend refused: {0}")]
     Spend(String),
 
+    /// The USER declined the spend at the confirm ceremony.
+    ///
+    /// Distinct from [`PolicyDenied`](Self::PolicyDenied) because the two are different facts about
+    /// different deciders, and a host reports them differently: "you said no" is an ordinary outcome,
+    /// while "the rules say no" may mean a misconfiguration. Merging them would also make the normative
+    /// wire mapping (`SPEC.md` §6.3.1) ambiguous — one crate outcome cannot map to two codes — and
+    /// collapsing outcomes at a boundary is the defect this crate's 0.2.0 shape exists to remove.
+    ///
+    /// Terminal: no further ceremony may permit a spend the user has already refused.
+    #[error("the user declined the spend: {0}")]
+    UserDeclined(String),
+
     /// The spend is FORBIDDEN by a structural custody rule, or the user declined it — no (further)
     /// confirmation ceremony can permit it.
     ///

src/lib.rs

@@ -41,6 +41,7 @@ pub mod keys;
 pub mod model;
 pub mod profile_mint;
 pub mod session;
+pub mod session_residency;
 pub mod signer;
 pub mod store;
 pub mod unlocked;
@@ -57,6 +58,7 @@ pub use keys::wallet_key::WalletKey;
 pub use model::{Account, AccountRecord, Profile};
 pub use profile_mint::ProfileMinter;
 pub use session::AccountSession;
+pub use session_residency::Residency;
 pub use signer::ProfileSigner;
 pub use store::{AccountStore, AccountStoreError};
 pub use unlocked::UnlockedAccount;

src/session_residency.rs

@@ -0,0 +1,82 @@
+//! [`Residency`] — the shared liveness token that makes `lock()` authoritative.
+//!
+//! # Why a token rather than dropping the seed
+//!
+//! The live seed sits behind an `Arc<UnlockedMasterSeed>`, and every capability handle
+//! ([`WalletOps`](crate::wallet::authorizer::WalletOps), the money signer) holds a clone of it. So
+//! dropping the [`UnlockedAccount`](crate::unlocked::UnlockedAccount) drops only ONE reference: while
+//! any capability handle survives, the seed is neither dropped nor zeroized, and anything built from it
+//! keeps working. `lock()` looked like a revocation and was really a hint.
+//!
+//! A `Residency` closes that. Every capability derived from one unlock shares the same token, and
+//! [`revoke`](Residency::revoke) flips it once for all of them. A signer therefore OBSERVES the session
+//! rather than owning a snapshot of it: after `lock()`, after a password change, after a profile switch,
+//! signing fails with [`Locked`](crate::error::AccountError::Locked) — even though the seed bytes may
+//! still be resident because some other handle is alive.
+//!
+//! This is deliberately an ENFORCEMENT rather than a documented obligation. The previous design's
+//! answer to "what stops a stale signer signing?" was a note asking hosts to rebuild the signer after
+//! the ceremony — the same unenforced-convention shape as the `SpendAuthorizer` trait this crate
+//! removed. A host cannot forget to check a flag it does not own.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+
+/// The liveness of ONE unlock, shared by every capability derived from it.
+///
+/// Starts live and becomes revoked at most once; there is deliberately no way back. A relock is a new
+/// unlock, which mints a new token — so a revoked `Residency` can never be resurrected by holding a
+/// reference to it.
+#[derive(Debug)]
+pub struct Residency {
+    live: AtomicBool,
+}
+
+impl Residency {
+    /// A live residency for a freshly-unlocked account.
+    pub(crate) fn new() -> Self {
+        Self {
+            live: AtomicBool::new(true),
+        }
+    }
+
+    /// Whether the unlock this token belongs to is still live.
+    ///
+    /// `Acquire`/`Release` ordering pairs with [`revoke`](Self::revoke): a thread that observes the
+    /// revocation also observes everything the revoking thread did before it, so a relock cannot be
+    /// seen half-applied.
+    pub fn is_live(&self) -> bool {
+        self.live.load(Ordering::Acquire)
+    }
+
+    /// Revoke the unlock. Idempotent, and irreversible.
+    pub(crate) fn revoke(&self) {
+        self.live.store(false, Ordering::Release);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+
+    #[test]
+    fn a_fresh_residency_is_live_and_revocation_is_visible_through_every_clone() {
+        let residency = Arc::new(Residency::new());
+        let capability = residency.clone();
+        assert!(capability.is_live());
+
+        residency.revoke();
+        assert!(
+            !capability.is_live(),
+            "a capability holding its own reference must observe the revocation"
+        );
+    }
+
+    #[test]
+    fn revocation_is_idempotent_and_has_no_way_back() {
+        let residency = Residency::new();
+        residency.revoke();
+        residency.revoke();
+        assert!(!residency.is_live());
+    }
+}

src/unlocked.rs

@@ -12,6 +12,7 @@ use zeroize::Zeroizing;
 
 use crate::id::{AccountId, ProfileIx};
 use crate::keys::dek::profile_dek;
+use crate::session_residency::Residency;
 use crate::signer::ProfileSigner;
 use crate::wallet::authorizer::WalletOps;
 
@@ -33,6 +34,9 @@ pub struct UnlockedAccount {
     account: AccountId,
     seed: Arc<UnlockedMasterSeed>,
     default_profile_ix: ProfileIx,
+    /// The liveness token every capability derived from this unlock shares, so
+    /// [`lock`](Self::lock) revokes them all rather than merely dropping one reference to the seed.
+    residency: Arc<Residency>,
 }
 
 impl UnlockedAccount {
@@ -46,9 +50,18 @@ impl UnlockedAccount {
             account,
             seed,
             default_profile_ix,
+            residency: Arc::new(Residency::new()),
         }
     }
 
+    /// The liveness token for this unlock — live until [`lock`](Self::lock).
+    ///
+    /// Exposed so a host can ask whether the capabilities it holds are still valid without having to
+    /// attempt an operation. It cannot be revoked through this handle.
+    pub fn residency(&self) -> Arc<Residency> {
+        self.residency.clone()
+    }
+
     /// The account this handle unlocked.
     pub fn account_id(&self) -> &AccountId {
         &self.account
@@ -65,8 +78,16 @@ impl UnlockedAccount {
     }
 
     /// The wallet-ops handle for the default profile (money-path derivations + signing seam).
+    ///
+    /// The handle observes this unlock's [`Residency`], so a money signer built from it stops signing
+    /// the moment [`lock`](Self::lock) is called — it does not hold a snapshot that outlives the
+    /// session.
     pub fn wallet_ops(&self) -> WalletOps {
-        WalletOps::new(self.seed.clone(), self.default_profile_ix)
+        WalletOps::new(
+            self.seed.clone(),
+            self.default_profile_ix,
+            self.residency.clone(),
+        )
     }
 
     /// The per-profile data-encryption key (DEK) for profile `ix` — 32 bytes, derived from the seed
@@ -82,10 +103,16 @@ impl UnlockedAccount {
         self.seed.master_seed()
     }
 
-    /// Relock immediately, dropping the live seed.
+    /// Relock immediately: revoke every capability derived from this unlock, and drop the seed.
+    ///
+    /// Revoking is what makes this authoritative. Consuming `self` drops only ONE reference to the
+    /// seed, so a surviving [`WalletOps`] would otherwise keep the bytes resident AND keep signing;
+    /// after this call such a handle refuses with [`Locked`](crate::error::AccountError::Locked)
+    /// regardless of who else still holds the seed.
     pub fn lock(self) {
-        // Consuming `self` drops the `Arc<UnlockedMasterSeed>`; when the last handle drops, the seed
-        // is zeroized.
+        self.residency.revoke();
+        // Dropping `self` releases this handle's `Arc<UnlockedMasterSeed>`; the bytes are zeroized
+        // once the last surviving handle drops.
     }
 }
 

src/wallet/approval.rs

@@ -34,8 +34,9 @@
 use chia_protocol::CoinSpend;
 use dig_wallet_backend::types::TransactionSummary;
 
-use crate::auth::provider::SpendDecision;
+use crate::auth::provider::{AuthProvider, SpendConfirmRequest, SpendDecision};
 use crate::error::{AccountError, Result};
+use crate::id::{AccountId, ProfileIx};
 use crate::wallet::summary::SpendSummary;
 
 /// The spends a ruling was made about, together with the single derivation made from them.
@@ -48,9 +49,14 @@ struct AuthorizedSpend {
     coin_spends: Vec<CoinSpend>,
     /// This crate's tiered, human-renderable view of those spends.
     summary: SpendSummary,
-    /// `dig-wallet-backend`'s own verified re-parse of the same spends, carried so the signer can
-    /// hand it back for the pre-signing cross-check without re-deriving it (one derivation, one
-    /// answer — two derivations could disagree).
+    /// The hinted-only summary `dig-wallet-backend`'s signer takes as a required PARAMETER, derived by
+    /// the gate alongside `summary` so the signer never has to re-parse the spend.
+    ///
+    /// The signer does compare it against its own re-derivation, but this crate does not treat that as
+    /// a check and does not rely on it: both sides come from these same bytes, so it can only agree. A
+    /// genuine second opinion would need an INDEPENDENT derivation — exactly the two-answers-can-
+    /// disagree shape this whole type exists to remove. What protects the caller is that `coin_spends`
+    /// below is the same `Vec` the gate judged.
     verified: TransactionSummary,
 }
 
@@ -129,29 +135,61 @@ impl PendingApproval {
         &self.inner.summary
     }
 
-    /// Convert the user's ruling into a signable approval.
+    /// Run the confirm ceremony through `provider`, and convert the user's ruling into a signable
+    /// approval.
+    ///
+    /// **This is the ONLY route from "needs a human" to a signature**, and it is a route THROUGH the
+    /// consent seam rather than past it. A host cannot mint an approval by asserting consent it never
+    /// obtained: it must implement [`AuthProvider::confirm_spend`], which is the seam that exists to
+    /// render the ceremony. A host that cannot render one MUST return
+    /// [`Decline`](SpendDecision::Decline) — never `Approve` — and `SPEC.md` §6.3 states that as a MUST.
     ///
-    /// Consumes `self`, so a ceremony cannot be run once and converted twice.
+    /// Consumes `self`, so one prompt yields at most one approval.
     ///
     /// # A decline is terminal, not a retry
     ///
-    /// [`Decline`](SpendDecision::Decline) yields [`PolicyDenied`](AccountError::PolicyDenied) rather
-    /// than an escalatable refusal: the human has already been asked, so no further ceremony may
-    /// permit this spend, and a caller that treated the decline as "ask again" would turn a refusal
-    /// into a prompt-until-mis-click.
+    /// [`Decline`](SpendDecision::Decline) yields [`UserDeclined`](AccountError::UserDeclined) — a
+    /// distinct variant from the structural [`PolicyDenied`](AccountError::PolicyDenied), so a host can
+    /// report "you said no" separately from "the rules say no" instead of collapsing them. Either way no
+    /// further ceremony may permit this spend: a caller that treated a decline as "ask again" would turn
+    /// a refusal into a prompt-until-mis-click.
     ///
     /// # A confirmed spend does not consume the auto-send allowance
     ///
-    /// The rolling period cap bounds what may move *unattended*. This spend moved because a human
-    /// said so, so it is charged to nothing — and, symmetrically, a declined spend leaves the
-    /// allowance untouched (a refusal must never cost the user their allowance). That is why this
-    /// method holds no reference to the gate's ledger: it structurally cannot charge it.
-    pub fn confirmed(self, decision: SpendDecision) -> Result<SpendApproval> {
+    /// The rolling period cap bounds what may move *unattended*. This spend moves because a human said
+    /// so, so it is charged to nothing — and, symmetrically, a declined spend leaves the allowance
+    /// untouched. Charging a confirmed spend would let anything that can raise a prompt drain the user's
+    /// unattended allowance without a single approval, turning the cap into a weapon against them.
+    /// `SPEC.md` §6.4 records the reasoning; this method holds no reference to the gate's ledger, so it
+    /// structurally cannot charge it either way.
+    pub async fn confirm_with(
+        self,
+        provider: &dyn AuthProvider,
+        account: AccountId,
+        profile: ProfileIx,
+    ) -> Result<SpendApproval> {
+        let request = SpendConfirmRequest::new(account, profile, self.inner.summary.clone());
+        let decision = provider.confirm_spend(request).await?;
+        self.decided(decision)
+    }
+
+    /// Convert an already-collected decision.
+    ///
+    /// `pub(crate)`: this is [`confirm_with`](Self::confirm_with)'s tail, and it is deliberately not a
+    /// public door. A public `confirmed(SpendDecision)` would let a host write
+    /// `RequiresConfirmation(p) => p.confirmed(Approve)` — one line, no user asked, no cap charged, no
+    /// limit re-checked. That is the `Ok(())` authorizer this crate removed, wearing a different name,
+    /// and with less accounting than the thing it replaced. Consent must come from the seam that exists
+    /// to obtain it.
+    fn decided(self, decision: SpendDecision) -> Result<SpendApproval> {
         match decision {
             SpendDecision::Approve => Ok(SpendApproval { inner: self.inner }),
-            SpendDecision::Decline(reason) => Err(AccountError::PolicyDenied(format!(
+            // `{:?}` deliberately: the reason is host-supplied text that may quote a dapp, and an
+            // error string ends up in logs. Debug-escaping it keeps a newline or a control character
+            // from forging a log line.
+            SpendDecision::Decline(reason) => Err(AccountError::UserDeclined(format!(
                 "the user declined this spend{}",
-                reason.map(|r| format!(": {r}")).unwrap_or_default()
+                reason.map(|r| format!(": {r:?}")).unwrap_or_default()
             ))),
         }
     }

src/wallet/authorizer.rs

@@ -23,6 +23,7 @@ use dig_wallet_backend::types::Network;
 use crate::error::Result;
 use crate::id::ProfileIx;
 use crate::keys::wallet_key::WalletKey;
+use crate::session_residency::Residency;
 use crate::wallet::money_signer::LocalMoneySigner;
 use crate::wallet::policy::CustodyPolicy;
 use crate::wallet::summary::SpendSummary;
@@ -32,12 +33,23 @@ use crate::wallet::summary::SpendSummary;
 pub struct WalletOps {
     seed: Arc<UnlockedMasterSeed>,
     profile_ix: ProfileIx,
+    /// The unlock this handle belongs to. Passed to every money signer it builds, so a signer cannot
+    /// outlive the session that authorized it.
+    residency: Arc<Residency>,
 }
 
 impl WalletOps {
-    /// Build the wallet-ops handle for `profile_ix`, backed by `seed`.
-    pub(crate) fn new(seed: Arc<UnlockedMasterSeed>, profile_ix: ProfileIx) -> Self {
-        Self { seed, profile_ix }
+    /// Build the wallet-ops handle for `profile_ix`, backed by `seed` and scoped to `residency`.
+    pub(crate) fn new(
+        seed: Arc<UnlockedMasterSeed>,
+        profile_ix: ProfileIx,
+        residency: Arc<Residency>,
+    ) -> Self {
+        Self {
+            seed,
+            profile_ix,
+            residency,
+        }
     }
 
     /// The profile's wallet (money) key, derived from the master seed at the profile index.
@@ -68,16 +80,26 @@ impl WalletOps {
 
     /// Build the profile's money signer for `network` — the concrete, canonical-wallet spend signer.
     ///
-    /// The signer is derived from the master seed over the CANONICAL
-    /// `master_to_wallet_unhardened(seed, ix).derive_synthetic()` money-key scheme (via
+    /// The signer signs over the CANONICAL `master_to_wallet_unhardened(seed, ix).derive_synthetic()`
+    /// money-key scheme (via
     /// [`LocalSigner::new_canonical`](dig_wallet_backend::client::LocalSigner::new_canonical)), so it
     /// controls the coins this profile's funds actually live at (byte-identical to
     /// [`public_key`](Self::public_key) / [`address`](Self::address)). The raw seed/key never leaves
     /// dig-account — the returned [`LocalMoneySigner`] exposes only signing.
-    pub fn money_signer(&self, network: Network) -> Result<LocalMoneySigner> {
+    ///
+    /// **The signer OBSERVES this unlock rather than copying it.** It holds the same
+    /// `Arc<UnlockedMasterSeed>` and the same [`Residency`] as this handle and derives the money key
+    /// per signature, so after
+    /// [`UnlockedAccount::lock`](crate::unlocked::UnlockedAccount::lock) it refuses. Holding a signer is
+    /// therefore not a way to keep a relocked account spendable.
+    ///
+    /// Infallible: building the signer defers every derivation to signing time, so there is nothing
+    /// here that can fail.
+    pub fn money_signer(&self, network: Network) -> LocalMoneySigner {
         LocalMoneySigner::new_canonical(
-            self.seed.master_seed().to_vec(),
-            self.profile_ix.0,
+            self.seed.clone(),
+            self.residency.clone(),
+            self.profile_ix,
             network,
         )
     }