dig-account 0.26.2

The DIG Network user Account: the fat, strictly-logical crate for everything an account does — the Account+Profile object model, unlock policy + keystore crypto, the in-process identity+money signer, per-profile key/DEK derivation, DID+dig-store mint/sign, and all wallet ops. Headless (no UI). Consumed by dig-app.
Documentation
//! [`ActiveProfile`] — the one active profile, and [`ActiveSwitch`] — what changed when it moved.

use crate::id::ProfileIx;
use crate::registry::entry::ProfileEntry;

/// The one active profile, BORROWED from the registry that vouches for it.
///
/// # What possessing one proves
///
/// Three things at once, none of which needs re-checking by the holder: the entry is PRESENT in the
/// registry, it is [`Shown`](crate::registry::ProfileVisibility::Shown), and it is the ACTIVE one.
/// The registry's invariants are what make all three true, and the only way to obtain this type is
/// [`ProfileRegistry::active`](crate::registry::ProfileRegistry::active).
///
/// Because it borrows the registry immutably, [`set_active`](crate::registry::ProfileRegistry::set_active)
/// — which needs `&mut` — cannot run while one is alive. **A stale active handle does not
/// typecheck**, so there is no window in which a host holds an active profile that the registry has
/// since moved away from.
///
/// This replaces dig-app's `ACTIVE_PROFILES: &[ProfileIx]` plus its
/// `const _: () = assert!(len() == 1)` tripwire (dig_ecosystem#2236). A slice can have a length
/// other than one and therefore needed the tripwire; a scalar field cannot, so the property is
/// structural rather than asserted.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ActiveProfile<'a>(&'a ProfileEntry);

impl<'a> ActiveProfile<'a> {
    /// Wrap the entry the registry has already established is present, shown, and active.
    pub(crate) fn new(entry: &'a ProfileEntry) -> Self {
        Self(entry)
    }

    /// The active profile's HD index — what every key-derivation call takes.
    pub fn ix(self) -> ProfileIx {
        self.0.ix()
    }

    /// The active profile's full entry.
    pub fn entry(self) -> &'a ProfileEntry {
        self.0
    }
}

impl From<ActiveProfile<'_>> for ProfileIx {
    fn from(active: ActiveProfile<'_>) -> Self {
        active.ix()
    }
}

/// What changed when the active slot moved.
///
/// # Why this is a value and not a `()`
///
/// A switch re-derives nothing and stores no key — every dig-account key API is
/// index-parameterized and derives per call — but it DOES change three things the user can be
/// surprised by: the receive address, the per-profile DEK, and the identity signing key. Funds at
/// the previous profile's address stay there and stay spendable; they do not follow the switch.
///
/// Rendering that is the HOST's ceremony (`SPEC.md` §1: dig-account draws no UI). This type's job is
/// to make the disclosure unavoidable — `#[must_use]` means a host that silently drops it has to say
/// so in code.
#[derive(Debug, Clone, PartialEq, Eq)]
#[must_use = "a host MUST disclose the receive-address change this switch causes"]
pub struct ActiveSwitch {
    /// The previously active profile, or `None` when there was none (the first profile of an
    /// account).
    pub from: Option<ProfileIx>,
    /// The now-active profile.
    pub to: ProfileIx,
}

/// What happened to the active slot when a profile ENDED on chain (dig_ecosystem#3067).
///
/// # Why this is not an [`ActiveSwitch`]
///
/// A switch always names a destination, because switching to nothing is not a switch. Ending the
/// account's LAST profile leaves no destination at all, and that state — a real one, reached by
/// deleting an only profile — is exactly what the registry previously had no way to express. Naming
/// the four outcomes separately keeps `ActiveSwitch::to` an honest `ProfileIx` rather than an
/// `Option` every existing caller would have to unwrap for a case that cannot happen to it.
#[derive(Debug, Clone, PartialEq, Eq)]
#[must_use = "a host MUST disclose an active-profile change the user did not choose"]
pub enum ProfileEndOutcome {
    /// The ended profile was not the active one; the active slot did not move.
    Recorded,
    /// The ended profile WAS active, and the slot moved to the lowest-indexed remaining live
    /// profile. The user did not choose this switch, so a host must say it happened.
    ActiveMoved(ActiveSwitch),
    /// The ended profile WAS active and NO live profile remains: the account now has no active
    /// profile at all. Every identity surface must stop claiming one.
    NoLiveProfileRemains,
    /// The profile had already ended. Nothing changed — recording an end twice is a no-op, so a
    /// host retrying after a crash mid-ceremony cannot move the active slot a second time.
    AlreadyEnded,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::mint::fixtures::bound_mint;
    use crate::registry::anchor::ProfileAnchor;

    #[test]
    fn an_active_profile_reports_the_entrys_index() {
        let (did, store) = bound_mint(1);
        let entry = ProfileEntry::new(
            ProfileIx(5),
            ProfileAnchor::from_confirmed(&did, &store).unwrap(),
            None,
        );
        let active = ActiveProfile::new(&entry);

        assert_eq!(active.ix(), ProfileIx(5));
        assert_eq!(ProfileIx::from(active), ProfileIx(5));
        assert_eq!(active.entry().ix(), ProfileIx(5));
    }
}