Skip to main content

dig_session/
unlocked.rs

1//! The unlocked-key handle and the signing primitive it injects.
2
3use std::sync::Arc;
4
5use dig_keystore::scheme::KeyScheme;
6use dig_keystore::SignerHandle;
7
8/// A scheme-parameterized signing primitive: a plain callable that maps a
9/// message to a signature and carries no dig-session or dig-identity type.
10///
11/// This is the shape [`UnlockedIdentity::inject_into`] hands to a consumer, so
12/// the consumer's API surface mentions only `&[u8]` in and `K::Signature`
13/// (a `chia_bls::Signature` for the BLS schemes) out — never a session or
14/// identity type. That is what keeps a consumer such as `dig-wallet-backend`
15/// identity-agnostic (see dig_ecosystem #908).
16pub type SigningFn<K> = Arc<dyn Fn(&[u8]) -> <K as KeyScheme>::Signature + Send + Sync>;
17
18/// A live, in-memory identity whose secret key has been decrypted and is ready
19/// to sign.
20///
21/// Obtained from [`crate::Session::unlock`] or [`crate::Session::enroll_identity`].
22/// The secret bytes live inside the wrapped [`SignerHandle`], which stores them
23/// in a `Zeroizing` buffer and wipes them when this value is dropped — so the
24/// decrypted key never lingers in freed memory. The type deliberately does not
25/// implement `Clone` and its `Debug` impl redacts the secret, so an
26/// `UnlockedIdentity` cannot be duplicated into a log line or a debug dump.
27///
28/// # Boundaries
29///
30/// An `UnlockedIdentity` must never cross an IPC boundary: it holds raw key
31/// material and belongs solely to the user-app process that owns the identity
32/// (dig_ecosystem #908). Hand a downstream a [`SigningFn`] via
33/// [`inject_into`](Self::inject_into) instead of the handle itself.
34pub struct UnlockedIdentity<K: KeyScheme> {
35    signer: SignerHandle<K>,
36    public_key: K::PublicKey,
37}
38
39impl<K: KeyScheme> UnlockedIdentity<K> {
40    /// Wrap a freshly unlocked [`SignerHandle`], caching its public key.
41    pub(crate) fn new(signer: SignerHandle<K>) -> Self {
42        let public_key = signer.public_key().clone();
43        Self { signer, public_key }
44    }
45
46    /// The public key of this identity.
47    ///
48    /// For the identity scheme this is byte-identical to
49    /// `dig_identity::public_key_bytes(derive_identity_sk(master))`, i.e. the
50    /// key anchored in the DID profile — so signatures produced by this handle
51    /// verify against the published identity.
52    pub fn public_key(&self) -> &K::PublicKey {
53        &self.public_key
54    }
55
56    /// Sign `msg` with the unlocked secret key.
57    pub fn sign(&self, msg: &[u8]) -> K::Signature {
58        self.signer.sign(msg)
59    }
60
61    /// Produce a standalone [`SigningFn`] primitive that signs with this
62    /// identity's key.
63    ///
64    /// The returned closure owns its own zeroizing copy of the secret, so it
65    /// keeps working after this handle is dropped and wipes its copy when the
66    /// closure itself is dropped.
67    pub fn signing_fn(&self) -> SigningFn<K> {
68        let signer = self.signer.clone();
69        Arc::new(move |msg: &[u8]| signer.sign(msg))
70    }
71
72    /// Inject this identity's signing capability into a consumer as a bare
73    /// [`SigningFn`] primitive, returning whatever the consumer builds from it.
74    ///
75    /// The consumer receives only a callable — never an `UnlockedIdentity`,
76    /// a `SignerHandle`, or any identity type — which is how a downstream stays
77    /// identity-agnostic while still being able to sign.
78    pub fn inject_into<T>(&self, consumer: impl FnOnce(SigningFn<K>) -> T) -> T {
79        consumer(self.signing_fn())
80    }
81}
82
83/// Redacting `Debug`: shows the type name only, never the secret (or even the
84/// public key, to avoid accidental correlation in logs).
85impl<K: KeyScheme> core::fmt::Debug for UnlockedIdentity<K> {
86    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
87        f.debug_struct("UnlockedIdentity")
88            .field("scheme", &K::NAME)
89            .field("secret", &"<redacted>")
90            .finish()
91    }
92}