Merge branch 'feature/extendable'; v13.1.0

Author: pjkundert

README.org

@@ -33,6 +33,7 @@
 
 from shamir_mnemonic	import EncryptedMasterSecret, split_ems
 from shamir_mnemonic.shamir import _random_identifier, RANDOM_BYTES
+from shamir_mnemonic.constants import ID_LENGTH_BITS
 
 import hdwallet
 from hdwallet		import cryptocurrencies
@@ -981,15 +982,16 @@ def group_parser( group_spec ):
 
 def create(
     name: str,
-    group_threshold: Optional[Union[int,float]] = None,		# Default: 1/2 of groups, rounded up
+    group_threshold: Optional[Union[int,float]] = None,  # Default: 1/2 of groups, rounded up
     groups: Optional[Union[List[str],Dict[str,Tuple[int, int]]]] = None,  # Default: 4 groups (see defaults.py)
-    master_secret: Optional[Union[str,bytes]] = None,		# Default: generate 128-bit Seed Entropy
+    master_secret: Optional[Union[str,bytes]] = None,   # Default: generate 128-bit Seed Entropy
     passphrase: Optional[Union[bytes,str]] = None,
     using_bip39: Optional[bool]	= None,  # Produce wallet Seed from master_secret Entropy using BIP-39 generation
     iteration_exponent: int	= 1,
     cryptopaths: Optional[Sequence[Union[str,Tuple[str,str],Tuple[str,str,str]]]] = None,  # default: ETH, BTC at default path, format
-    strength: Optional[int]	= None,				# Default: 128
-    extendable: Optional[Union[bool,int]] = None,		# Default: True w/ random identifier
+    strength: Optional[int]	= None,			# Default: 128
+    extendable: Optional[bool]	= None,			# Default: True
+    identifier: Optional[int]	= None,			# Default: random identifier
 ) -> Tuple[str,int,Dict[str,Tuple[int,List[str]]], Sequence[Sequence[Account]], bool]:
     """Creates a SLIP-39 encoding for supplied master_secret Entropy, and 1 or more Cryptocurrency
     accounts.  Returns the Details, in a form directly compatible with the layout.produce_pdf API.
@@ -1092,7 +1094,8 @@ def create(
         master_secret	= master_secret,
         passphrase	= passphrase,
         iteration_exponent= iteration_exponent,
-        extendable	= extendable
+        extendable	= extendable,
+        identifier	= identifier,
     )
 
     groups			= {
@@ -1120,7 +1123,8 @@ def mnemonics(
     passphrase: Optional[Union[bytes,str]] = None,
     iteration_exponent: int	= 1,
     strength: int		= BITS_DEFAULT,
-    extendable: Optional[Tuple[bool,int]] = None,
+    extendable: Optional[bool]	= None,			# Default: True
+    identifier: Optional[int]	= None,			# Default: random identifier
 ) -> List[List[str]]:
     """Generate SLIP39 mnemonics for the supplied master_secret for group_threshold of the given
      groups.  Will generate a random master_secret, if necessary.
@@ -1151,11 +1155,15 @@ def mnemonics(
             passphrase		= ""
         if isinstance( passphrase, str ):
             passphrase		= passphrase.encode( 'UTF-8' )
+        extendable		= False if extendable is False else True
+        identifier		= _random_identifier() if identifier is None else int( identifier )
+        assert isinstance( identifier, int) and 0 <= identifier < (1 << ID_LENGTH_BITS), \
+            "Identifier must be an {ID_LENGTH_BITS}-bit unsigned integer: {identifier}"
         encrypted_secret	= EncryptedMasterSecret.from_master_secret(
             master_secret = master_secret,
             passphrase	= passphrase,
-            identifier	= _random_identifier() if extendable in (None, False, True) else extendable,
-            extendable	= False if extendable is False else True,
+            identifier	= identifier,
+            extendable	= extendable,
             iteration_exponent = iteration_exponent,
         )
 

README.pdf

@@ -0,0 +1,60 @@
+#+title: Extendable
+#+OPTIONS: toc:nil title:nil author:nil
+
+#+BEGIN_ABSTRACT
+SLIP-39 Mnemonics recover a unique (but "valid") Seed and derived wallets, no matter what
+/alternative/ passphrase you use!  Your /original/ Seed can only be recovered with the originally
+specified "correct" passphrase.
+
+Extendable SLIP-39 Mnemonics ensures that all SLIP-39 Mnemonic sets generated from the /original/
+Seed and original "correct" passphrase will /always/ result in the same unique Seed for each
+/alternative/ passphrase.
+
+Non-Extendable SLIP-39 Mnemonics recover the /original/ Seed with the "correct" passphrase, but
+*different* unique Seeds for all /alternative/ passphrases.
+#+END_ABSTRACT
+
+* Extendable
+
+  The default is now /Extendable/ -- does /not/ use the Identifier to salt the encryption passphrase.
+
+** The Purpose for Multiple Passphrases
+
+   Recovering different Seeds for different passphrases is a valuable feature, because you may use
+   the same SLIP-39 Mnemonic cards, and supply different passphrases to recover different (but valid)
+   Seeds and sets of derived HD wallets!
+
+   - You could have a "distress" passphrase that recovers a decoy wallet containing a
+     small amount of sacrificial funds, while your real savings are under a different passphrase.
+   - One password for your personal accounts and another for business accounts.
+
+** Non-Extendable Encoding
+
+   Historically, the SLIP-39 encoding used the randomly assigned Identifier to both 1) associate groups
+   of Mnemonics belonging to the same set, but /also/ 2) to salt the Seed encryption.
+
+   This meant that: if you created 2 sets of SLIP-39 Mnemonics for the same Seed -- each set would
+   lead to */same/* Seed with the "correct" original passphrase, but to */different/* Seeds with
+   each "distress" passphrase!
+
+   Unless all sets of SLIP-39 Mnemonics lead to the same Seeds for each passphrase, you are
+   restricted to ever issue /only one/ set of SLIP-39 Mnemonics for each Seed!  You lose the ability
+   to recover other "distress" passphrase Seeds from the new sets of Mnemonics!
+
+** Issuing Multiple SLIP-39 Mnemonic Sets
+     
+   You may want to issue a simple set of SLIP-39 Mnemonics for your Seed to begin with, and then
+   (later) decide to issue a more elaborate set of SLIP-39 Mnenmonic cards.
+
+   Only with Extendable SLIP-39 Mnemonics, will the /alternative/ passphrase Seeds and derived
+   wallets be consistent. 
+
+* Recovery
+
+  The SLIP-39 App supports recovery from both Extendable and (historic) non-Extendable SLIP-39
+  Mnemonics.
+
+** Using [[https://iancoleman.io/slip39]]
+
+   Until the website is updated, you cannot (as of Dec 2024) use it to recover your Seed from
+   Extendable SLIP-39 Mnemonics.

README.txt

@@ -0,0 +1,78 @@
+SLIP-39 Mnemonics recover a unique (but "valid") Seed and derived
+wallets, no matter what /alternative/ passphrase you use!  Your
+/original/ Seed can only be recovered with the originally specified
+"correct" passphrase.
+
+Extendable SLIP-39 Mnemonics ensures that all SLIP-39 Mnemonic sets
+generated from the /original/ Seed and original "correct" passphrase
+will /always/ result in the same unique Seed for each /alternative/
+passphrase.
+
+Non-Extendable SLIP-39 Mnemonics recover the /original/ Seed with the
+"correct" passphrase, but *different* unique Seeds for all /alternative/
+passphrases.
+
+
+1 Extendable
+════════════
+
+  The default is now /Extendable/ – does /not/ use the Identifier to
+  salt the encryption passphrase.
+
+
+1.1 The Purpose for Multiple Passphrases
+────────────────────────────────────────
+
+  Recovering different Seeds for different passphrases is a valuable
+  feature, because you may use the same SLIP-39 Mnemonic cards, and
+  supply different passphrases to recover different (but valid) Seeds
+  and sets of derived HD wallets!
+
+  • You could have a "distress" passphrase that recovers a decoy wallet
+    containing a small amount of sacrificial funds, while your real
+    savings are under a different passphrase.
+  • One password for your personal accounts and another for business
+    accounts.
+
+
+1.2 Non-Extendable Encoding
+───────────────────────────
+
+  Historically, the SLIP-39 encoding used the randomly assigned
+  Identifier to both 1) associate groups of Mnemonics belonging to the
+  same set, but /also/ 2) to salt the Seed encryption.
+
+  This meant that: if you created 2 sets of SLIP-39 Mnemonics for the
+  same Seed – each set would lead to */same/* Seed with the "correct"
+  original passphrase, but to */different/* Seeds with each "distress"
+  passphrase!
+
+  Unless all sets of SLIP-39 Mnemonics lead to the same Seeds for each
+  passphrase, you are restricted to ever issue /only one/ set of SLIP-39
+  Mnemonics for each Seed!  You lose the ability to recover other
+  "distress" passphrase Seeds from the new sets of Mnemonics!
+
+
+1.3 Issuing Multiple SLIP-39 Mnemonic Sets
+──────────────────────────────────────────
+
+  You may want to issue a simple set of SLIP-39 Mnemonics for your Seed
+  to begin with, and then (later) decide to issue a more elaborate set
+  of SLIP-39 Mnenmonic cards.
+
+  Only with Extendable SLIP-39 Mnemonics, will the /alternative/
+  passphrase Seeds and derived wallets be consistent.
+
+
+2 Recovery
+══════════
+
+  The SLIP-39 App supports recovery from both Extendable and (historic)
+  non-Extendable SLIP-39 Mnemonics.
+
+
+2.1 Using <https://iancoleman.io/slip39>
+────────────────────────────────────────
+
+  Until the website is updated, you cannot (as of Dec 2024) use it to
+  recover your Seed from Extendable SLIP-39 Mnemonics.

images/SLIP39-Example.pdf

@@ -2,7 +2,7 @@
 #+OPTIONS: toc:nil title:nil author:nil
 
 #+BEGIN_ABSTRACT
-Bad Entropy is risk to Cryptocurrency HD Wallet Seed Secrets!
+Bad Entropy is a risk to Cryptocurrency HD Wallet Seed Secrets!
 
 Avoid Harmonic and Shannon Entropy Deficiencies:
   - Use strong cryptographically secure randomness for your Seed Data

slip39/api.py

@@ -1,4 +1,4 @@
-Bad Entropy is risk to Cryptocurrency HD Wallet Seed Secrets!
+Bad Entropy is a risk to Cryptocurrency HD Wallet Seed Secrets!
 
 Avoid Harmonic and Shannon Entropy Deficiencies:
 • Use strong cryptographically secure randomness for your Seed Data

slip39/gui/SLIP-39-EXTENDABLE.org

@@ -57,7 +57,7 @@
                                   "academic acid beard romp believe impulse species holiday demand building" \
                                   " earth warn lunar olympic clothes piece campus alpha short endless"
 
-SD_SEED_FRAME			= 'Seed Source: Create your Seed Entropy here'
+SD_SEED_FRAME			= 'Seed Source: Create/Recover Seed Entropy here'
 SE_SEED_FRAME			= 'Seed Extra Randomness'
 SS_SEED_FRAME			= 'Seed Secret & SLIP-39 Recovery Groups'
 
@@ -269,16 +269,17 @@ def groups_layout(
         ],
     ] + [
         [
-            # SLIP-39 only available in Recovery; SLIP-39 Passphrase only in Pro; BIP-39 and Fixed Hex only in Pro
+            # SLIP-39 only available in Recovery; SLIP-39 Passphrase only in Pro
             sg.Frame( SD_SEED_FRAME, [
                 [
                     sg.Text( "Random:" if not LO_BAK else "Source:",            visible=LO_CRE, **T_hue( T_kwds, 0/20 )),
-                    sg.Radio( "128-bit",          "SD", key='-SD-128-RND-',     default=LO_CRE,
+                    sg.Radio( "128-bit",          "SD", key='-SD-128-RND-',     visible=LO_CRE, **T_hue( B_kwds, 0/20 )),
+                    sg.Radio( "256-bit",          "SD", key='-SD-256-RND-',     default=LO_CRE and not LO_REC,
                                                                                 visible=LO_CRE, **T_hue( B_kwds, 0/20 )),
-                    sg.Radio( "256-bit",          "SD", key='-SD-256-RND-',     visible=LO_CRE, **T_hue( B_kwds, 0/20 )),
                     sg.Radio( "512-bit",          "SD", key='-SD-512-RND-',     visible=LO_PRO, **T_hue( B_kwds, 0/20 )),
                     sg.Text( "Recover:",                                        visible=LO_CRE, **T_hue( T_kwds, 2/20 )),
-                    sg.Radio( "SLIP-39",          "SD", key='-SD-SLIP-',        visible=LO_REC, **T_hue( B_kwds, 2/20 )),
+                    sg.Radio( "SLIP-39",          "SD", key='-SD-SLIP-',        default=LO_REC,
+                                                                                visible=LO_REC, **T_hue( B_kwds, 2/20 )),
                     sg.Radio( "BIP-39",           "SD", key='-SD-BIP-',         default=LO_BAK,
                                                                                 visible=LO_CRE, **T_hue( B_kwds, 2/20 )),
                     sg.Radio( "BIP-39 Seed",      "SD", key='-SD-BIP-SEED-',    visible=LO_PRO, **T_hue( B_kwds, 2/20 )),
@@ -367,6 +368,9 @@ def groups_layout(
                             sg.Text( f"of {len(groups)}", key='-RECOVERY-',                     **T_kwds ),
                             sg.Button( '+', **B_kwds ),
                             sg.Text( "Mnemonic Card Groups",                                    **T_kwds ),
+                            sg.Checkbox( "Extendable",  key='-EXTENDABLE-',     visible=LO_CRE,
+                                                                                default=True,
+                                                                                size=prefix,    **T_hue( B_kwds, +1/20 )),
                         ],
                         group_body,
                     ] ),
@@ -595,12 +599,12 @@ def update_seed_data( event, window, values ):
         # We're recovering the BIP-39 Seed Phrase *Entropy*, NOT the derived (decrypted) 512-bit
         # Seed Data!  So, we don't deal in Passphrases, here.  The Passphrase (to encrypt the Seed,
         # when "Using BIP-39") is only required to display the correct wallet addresses.
-        window['-SD-DATA-F-'].update( "BIP-39 Mnemonic to Back Up: " )
+        window['-SD-DATA-F-'].update( "BIP-39 Mnemonic to Recover or Back Up: " )
         window['-SD-DATA-F-'].update( visible=True )
         window['-SD-PASS-C-'].update( visible=False )
         window['-SD-PASS-F-'].update( visible=False )
     elif 'SLIP' in update_seed_data.src:
-        window['-SD-DATA-F-'].update( "SLIP-39 Mnemonics to Back Up: " )
+        window['-SD-DATA-F-'].update( "SLIP-39 Mnemonics to Recover or Back Up: " )
         window['-SD-DATA-F-'].update( visible=True )
         window['-SD-PASS-C-'].update( visible=True )
         window['-SD-PASS-F-'].update(
@@ -1073,6 +1077,7 @@ def app(
     events_ignored		= ('-MNEMONICS-'+sg.WRITE_ONLY_KEY,)
     master_secret		= None		# default to produce randomly
     details			= None		# The SLIP-39 details produced from groups; make None to force SLIP-39 Mnemonic update
+    extendable			= True
     cryptopaths			= None
     timeout			= 0		# First time thru; refresh immediately; functions req. refresh may adjust via values['__TIMEOUT__']
     instructions		= ''		# The last instructions .txt payload found
@@ -1441,6 +1446,11 @@ def deficiency( *deficiencies ):
         # We avoid recomputing this unless something about the seed or the recovered groups changes;
         # each time we recompute -- even without any changes -- the SLIP-39 Mnemonics will change,
         # due to the use of entropy in the SLIP-39 process.
+        extendable_rec		= values['-EXTENDABLE-']
+        if extendable_rec != extendable:
+            extendable		= extendable_rec
+            details		= None
+
         if not details or names[0] not in details:
             log.info( f"SLIP39 details for {names}..." )
             try:
@@ -1457,6 +1467,7 @@ def deficiency( *deficiencies ):
                         passphrase	= passphrase,
                         using_bip39	= using_bip39,
                         cryptopaths	= cryptopaths,
+                        extendable	= extendable,
                     )
             except Exception as exc:
                 status		= f"Error creating: {exc}"
@@ -1532,7 +1543,7 @@ def deficiency( *deficiencies ):
                 continue
             name_len		= max( len( name ) for name in details )
             status		= '\n'.join(
-                f"Saved {name}"
+                f"{'Print' if printer else 'Saved'}: {name}"
                 for name in details
             )
         # Finally, success has been assured; turn off emboldened status line