-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
27 lines (27 loc) · 21.1 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!DOCTYPE html><html class="default" lang="en"><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@holochain/hc-seed-bundle</title><meta name="description" content="Documentation for @holochain/hc-seed-bundle"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">@holochain/hc-seed-bundle</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h2>@holochain/hc-seed-bundle</h2></div><div class="tsd-panel tsd-typography"><a id="md:holochainhc-seed-bundle" class="tsd-anchor"></a><h1><a href="#md:holochainhc-seed-bundle">@holochain/hc-seed-bundle</a></h1><p><a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache-2.0"></a></p>
<p>TypeScript SeedBundle parsing and generation library.</p>
<a id="md:links" class="tsd-anchor"></a><h3><a href="#md:links">Links</a></h3><ul>
<li><a href="https://github.com/holochain/hcSeedBundle">Git Repo - https://github.com/holochain/hcSeedBundle</a></li>
<li><a href="https://holochain.github.io/hcSeedBundle/">API Documentation - https://holochain.github.io/hcSeedBundle/</a></li>
</ul>
<a id="md:rationale" class="tsd-anchor"></a><h3><a href="#md:rationale">Rationale</a></h3><ul>
<li>Applications like Holochain have different requirements than classic blockchain system in terms of key management. Namely there is no need for read-only or hardened wallets (Holochain handles these concepts through capabilities and membranes).</li>
<li>Applications like Holochain still have need of hierarchy and determinism in key (or in this case seed) derivation.</li>
<li>Since we're using libsodium for hashing, signature, and encryption algorithms, let's use it for derivation as well.</li>
<li>To be psychologically compatible with the <a href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">Bitcoin "HD Wallet" spec</a>, we will do away with the "context" part of sodium KDF by always setting it to <code>b"SeedBndl"</code> and focusing on the <code>subkey_id</code> and can declare a chain of subsequent derivations of a 32 byte seed in the form <code>m/68/1/65/8</code> where we apply <code>subkey_id</code>s 68, 1, 65, then 8 in turn.</li>
</ul>
<a id="md:derivation-usage" class="tsd-anchor"></a><h3><a href="#md:derivation-usage">Derivation Usage</a></h3><pre><code class="language-typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">, </span><span class="hl-2">seedBundleReady</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">"@holochain/hc-seed-bundle"</span><span class="hl-1">;</span><br/><br/><span class="hl-4">// await library functions ready to call</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">seedBundleReady</span><span class="hl-1">;</span><br/><br/><span class="hl-4">// generate a new pure entropy master seed</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">master</span><span class="hl-1"> = </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">.</span><span class="hl-7">newRandom</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">bundleType:</span><span class="hl-1"> </span><span class="hl-3">"master"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">// derive a device root seed from the master</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">deviceRoot</span><span class="hl-1"> = </span><span class="hl-2">master</span><span class="hl-1">.</span><span class="hl-7">derive</span><span class="hl-1">(</span><span class="hl-8">68</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">bundleType:</span><span class="hl-1"> </span><span class="hl-3">"deviceRoot"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">// clear our secrets</span><br/><span class="hl-2">master</span><span class="hl-1">.</span><span class="hl-7">zero</span><span class="hl-1">();</span><br/><span class="hl-2">deviceRoot</span><span class="hl-1">.</span><span class="hl-7">zero</span><span class="hl-1">();</span>
</code><button>Copy</button></pre>
<a id="md:locking-encrypting-a-seedbundle" class="tsd-anchor"></a><h3><a href="#md:locking-encrypting-a-seedbundle">Locking (encrypting) a SeedBundle</a></h3><pre><code class="language-typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">, </span><span class="hl-2">SeedCipherPwHash</span><span class="hl-1">, </span><span class="hl-2">seedBundleReady</span><span class="hl-1">, </span><span class="hl-2">parseSecret</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">"@holochain/hc-seed-bundle"</span><span class="hl-1">;</span><br/><br/><span class="hl-4">// await library functions ready to call</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">seedBundleReady</span><span class="hl-1">;</span><br/><br/><span class="hl-4">// generate a new pure entropy master seed</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">master</span><span class="hl-1"> = </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">.</span><span class="hl-7">newRandom</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">bundleType:</span><span class="hl-1"> </span><span class="hl-3">"master"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">// we need the passphrase as a Uint8Array</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">pw</span><span class="hl-1"> = </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-7">TextEncoder</span><span class="hl-1">().</span><span class="hl-7">encode</span><span class="hl-1">(</span><span class="hl-3">"test-passphrase"</span><span class="hl-1">);</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">encodedBytes</span><span class="hl-1"> = </span><span class="hl-2">master</span><span class="hl-1">.</span><span class="hl-7">lock</span><span class="hl-1">([</span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-7">SeedCipherPwHash</span><span class="hl-1">(</span><span class="hl-7">parseSecret</span><span class="hl-1">(</span><span class="hl-2">pw</span><span class="hl-1">), </span><span class="hl-3">"minimum"</span><span class="hl-1">)]);</span><br/><br/><span class="hl-4">// -- if you want to regenerate for (decrypting) below:</span><br/><span class="hl-4">// console.log(Buffer.from(encodedBytes).toString('base64'))</span><br/><br/><span class="hl-4">// clear our secrets</span><br/><span class="hl-2">master</span><span class="hl-1">.</span><span class="hl-7">zero</span><span class="hl-1">();</span>
</code><button>Copy</button></pre>
<a id="md:locking-encrypting-a-seedbundle-with-security-questions" class="tsd-anchor"></a><h3><a href="#md:locking-encrypting-a-seedbundle-with-security-questions">Locking (encrypting) a SeedBundle with Security Questions</a></h3><pre><code class="language-typescript"><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">SeedCipherSecurityQuestions</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">seedBundleReady</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">parseSecret</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">"@holochain/hc-seed-bundle"</span><span class="hl-1">;</span><br/><br/><span class="hl-4">// await library functions ready to call</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">seedBundleReady</span><span class="hl-1">;</span><br/><br/><span class="hl-4">// generate a new pure entropy master seed</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">master</span><span class="hl-1"> = </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">.</span><span class="hl-7">newRandom</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">bundleType:</span><span class="hl-1"> </span><span class="hl-3">"master"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">// we need the answers as a Uint8Arrays</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">pw</span><span class="hl-1"> = (</span><span class="hl-2">pw</span><span class="hl-1">: </span><span class="hl-9">string</span><span class="hl-1">) </span><span class="hl-5">=></span><span class="hl-1"> </span><span class="hl-7">parseSecret</span><span class="hl-1">(</span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-7">TextEncoder</span><span class="hl-1">().</span><span class="hl-7">encode</span><span class="hl-1">(</span><span class="hl-2">pw</span><span class="hl-1">));</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">encodedBytes</span><span class="hl-1"> = </span><span class="hl-2">master</span><span class="hl-1">.</span><span class="hl-7">lock</span><span class="hl-1">([</span><br/><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-7">SeedCipherSecurityQuestions</span><span class="hl-1">(</span><br/><span class="hl-1"> [</span><span class="hl-3">"Favorite Color?"</span><span class="hl-1">, </span><span class="hl-3">"Favorite Hair?"</span><span class="hl-1">, </span><span class="hl-3">"Favorite Food?"</span><span class="hl-1">],</span><br/><span class="hl-1"> [</span><span class="hl-7">pw</span><span class="hl-1">(</span><span class="hl-3">"blue"</span><span class="hl-1">), </span><span class="hl-7">pw</span><span class="hl-1">(</span><span class="hl-3">"big"</span><span class="hl-1">), </span><span class="hl-7">pw</span><span class="hl-1">(</span><span class="hl-3">"begal"</span><span class="hl-1">)],</span><br/><span class="hl-1"> </span><span class="hl-3">"minimum"</span><span class="hl-1">,</span><br/><span class="hl-1"> ),</span><br/><span class="hl-1">]);</span><br/><br/><span class="hl-4">// clear our secrets</span><br/><span class="hl-2">master</span><span class="hl-1">.</span><span class="hl-7">zero</span><span class="hl-1">();</span>
</code><button>Copy</button></pre>
<a id="md:unlocking-decrypting-a-seedbundle" class="tsd-anchor"></a><h3><a href="#md:unlocking-decrypting-a-seedbundle">Unlocking (decrypting) a SeedBundle</a></h3><pre><code class="language-typescript"><span class="hl-4">// await library functions ready to call</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">, </span><span class="hl-2">LockedSeedCipherPwHash</span><span class="hl-1">, </span><span class="hl-2">seedBundleReady</span><span class="hl-1">, </span><span class="hl-2">parseSecret</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">"@holochain/hc-seed-bundle"</span><span class="hl-1">;</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">seedBundleReady</span><span class="hl-1">;</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">encodedBytes</span><span class="hl-1"> = </span><span class="hl-2">Buffer</span><span class="hl-1">.</span><span class="hl-7">from</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-3">"k6VoY3NiMJGWonB3xBD5Ov1Vas4XnV1XPsf8ddCqzSAAAcQYkO36tg8NHoec02I7KtxfX+ZnmBzIz+SoxDFDNfr4/9811ugf18FiRSywOyVagFHIRTyrfV3jZLRt6W0r7WuepaQLjlFu4jgVMrd2xBOBqmJ1bmRsZVR5cGWmbWFzdGVy"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-3">"base64"</span><span class="hl-1">,</span><br/><span class="hl-1">);</span><br/><span class="hl-4">// decode the SeedCiphers that will let us unlock this bundle</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">cipherList</span><span class="hl-1"> = </span><span class="hl-2">UnlockedSeedBundle</span><span class="hl-1">.</span><span class="hl-7">fromLocked</span><span class="hl-1">(</span><span class="hl-2">encodedBytes</span><span class="hl-1">);</span><br/><span class="hl-4">// the demo is encrypted with PwHash</span><br/><span class="hl-0">if</span><span class="hl-1"> (!(</span><span class="hl-2">cipherList</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">] </span><span class="hl-5">instanceof</span><span class="hl-1"> </span><span class="hl-9">LockedSeedCipherPwHash</span><span class="hl-1">)) {</span><br/><span class="hl-1"> </span><span class="hl-0">throw</span><span class="hl-1"> </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-7">Error</span><span class="hl-1">(</span><span class="hl-3">"Expecting PwHash"</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-4">// unlock with the passphrase</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">pw</span><span class="hl-1"> = </span><span class="hl-5">new</span><span class="hl-1"> </span><span class="hl-7">TextEncoder</span><span class="hl-1">().</span><span class="hl-7">encode</span><span class="hl-1">(</span><span class="hl-3">"test-passphrase"</span><span class="hl-1">);</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-6">master</span><span class="hl-1"> = </span><span class="hl-2">cipherList</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">].</span><span class="hl-7">unlock</span><span class="hl-1">(</span><span class="hl-7">parseSecret</span><span class="hl-1">(</span><span class="hl-2">pw</span><span class="hl-1">));</span><br/><br/><span class="hl-4">// clear our secrets</span><br/><span class="hl-2">master</span><span class="hl-1">.</span><span class="hl-7">zero</span><span class="hl-1">();</span>
</code><button>Copy</button></pre>
<a id="md:development" class="tsd-anchor"></a><h1><a href="#md:development">Development</a></h1><a id="md:to-install-dependencies" class="tsd-anchor"></a><h3><a href="#md:to-install-dependencies">To install dependencies</a></h3><pre><code class="language-bash"><span class="hl-7">bun</span><span class="hl-1"> </span><span class="hl-3">install</span>
</code><button>Copy</button></pre>
<p>To run:</p>
<pre><code class="language-bash"><span class="hl-7">bun</span><span class="hl-1"> </span><span class="hl-3">run</span><span class="hl-1"> </span><span class="hl-3">index.ts</span>
</code><button>Copy</button></pre>
<p>This project was created using <code>bun init</code> in bun v1.1.8. <a href="https://bun.sh">Bun</a> is a fast all-in-one JavaScript runtime.</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-index-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><h4 class="uppercase">Member Visibility</h4><form><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-private" name="private"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Private</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></form></div><div class="tsd-theme-toggle"><h4 class="uppercase">Theme</h4><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-index-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#md:holochainhc-seed-bundle"><span>@holochain/hc-<wbr/>seed-<wbr/>bundle</span></a><ul><li><ul><li><a href="#md:links"><span>Links</span></a></li><li><a href="#md:rationale"><span>Rationale</span></a></li><li><a href="#md:derivation-usage"><span>Derivation <wbr/>Usage</span></a></li><li><a href="#md:locking-encrypting-a-seedbundle"><span>Locking (encrypting) a <wbr/>Seed<wbr/>Bundle</span></a></li><li><a href="#md:locking-encrypting-a-seedbundle-with-security-questions"><span>Locking (encrypting) a <wbr/>Seed<wbr/>Bundle with <wbr/>Security <wbr/>Questions</span></a></li><li><a href="#md:unlocking-decrypting-a-seedbundle"><span>Unlocking (decrypting) a <wbr/>Seed<wbr/>Bundle</span></a></li></ul></li></ul><a href="#md:development"><span>Development</span></a><ul><li><a href="#md:to-install-dependencies"><span>To install dependencies</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current"><svg class="tsd-kind-icon" viewBox="0 0 24 24"><use href="assets/icons.svg#icon-1"></use></svg><span>@holochain/hc-seed-bundle</span></a><ul class="tsd-small-nested-navigation" id="tsd-nav-container" data-base="."><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>