@gryt/crypto 0.2.0 → 0.4.0

package/README.md

@@ -1,7 +1,14 @@
-# @gryt/crypto
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Gryt-chat/client/main/public/logo.svg" width="80" alt="Gryt logo" />
+  <h1>@gryt/crypto</h1>
+  <p>Message encryption for <a href="https://gryt.chat">Gryt</a>.<br />Key derivation, key bindings, sealed envelopes, pinning, and the code two people compare out of band.</p>
+</div>
 
-Message encryption for [Gryt](https://gryt.chat): key derivation, key bindings,
-sealed envelopes, pinning, and the code two people compare out of band.
+<br />
+
+```sh
+npm install @gryt/crypto
+```
 
 Used by the desktop client and the mobile app. They run this, not two ports of
 it — two implementations of one envelope is a pair of clients that send each
@@ -72,6 +79,20 @@ what a client installs. `check-crypto-vectors.mjs` holds bytes produced before
 the WebCrypto-to-noble conversion and nothing regenerates them — a change that
 quietly altered the envelope would leave every message already sent unreadable.
 
-## Licence
+## Issues
+
+Please report bugs and request features in the
+[main Gryt repository](https://github.com/Gryt-chat/gryt/issues).
+
+## Sponsors
+
+What sponsoring pays for, the tiers, and everyone who has sponsored:
+[gryt.chat/sponsors](https://gryt.chat/sponsors). To sponsor:
+[GitHub Sponsors](https://github.com/sponsors/Gryt-chat).
+
+The list itself lives in the [Gryt README](https://github.com/Gryt-chat/gryt#sponsors),
+in one place rather than ten, so it cannot fall out of step across repositories.
+
+## License
 
-AGPL-3.0-only.
+[AGPL-3.0](https://github.com/Gryt-chat/gryt/blob/main/LICENSE) — Part of [Gryt](https://github.com/Gryt-chat/gryt)

package/dist/index.d.ts

@@ -33,6 +33,7 @@
  * setting.
  */
 export * from "./attachments.js";
+export * from "./base64.js";
 export * from "./comparison-code.js";
 export * from "./conversation-encryption.js";
 export * from "./dm-key-binding.js";
@@ -41,4 +42,5 @@ export * from "./member-keys.js";
 export * from "./message-keys.js";
 export * from "./peer-keys.js";
 export * from "./scope.js";
+export * from "./seed-words.js";
 export * from "./thumbprint.js";

package/dist/index.js

@@ -33,6 +33,10 @@
  * setting.
  */
 export * from "./attachments.js";
+// Exported because both apps carry their own copy of exactly this, and one of
+// the two is the `btoa` version this file was written to replace. They cannot
+// drop theirs while it is package-internal.
+export * from "./base64.js";
 export * from "./comparison-code.js";
 export * from "./conversation-encryption.js";
 export * from "./dm-key-binding.js";
@@ -41,4 +45,5 @@ export * from "./member-keys.js";
 export * from "./message-keys.js";
 export * from "./peer-keys.js";
 export * from "./scope.js";
+export * from "./seed-words.js";
 export * from "./thumbprint.js";

package/dist/seed-words.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The identity seed as 24 words, and back.
+ *
+ * Both apps had this, and a phrase written down from one has to restore on the
+ * other or it is worthless. They agreed — same wordlist, same BIP-39 calls, the
+ * same 24 — but they agreed by two people keeping two files in step, which is
+ * the arrangement this package exists to end.
+ *
+ * The standard 2048-word list is 11 bits a word: 256 bits of seed plus 8 bits of
+ * checksum makes 264, which is 24 words exactly. The checksum lives inside the
+ * words rather than beside them, so a mistyped or reordered phrase is rejected
+ * instead of quietly producing a different identity — and since no two words in
+ * the list share their first four letters, a misread word usually is not a word
+ * at all and fails before the checksum is reached.
+ *
+ * Only the encoding is borrowed from wallets. The key-stretching step they do on
+ * top is not wanted here: these 256 bits are the seed already, not a passphrase
+ * to grind into one.
+ */
+/** Length of the seed every local identity is calculated from. */
+export declare const SEED_BYTES = 32;
+/** How many words a backup is. Stated once so the message and the check agree. */
+export declare const BACKUP_WORDS = 24;
+/**
+ * Refuse a seed that cannot be one.
+ *
+ * The length check is the real one. The repeated-byte check is for a generator
+ * that has failed open and is handing back zeros, which is worth catching loudly
+ * rather than deriving a whole identity from.
+ */
+export declare function assertUsableSeed(seed: Uint8Array): void;
+export declare function seedToWords(seed: Uint8Array): string;
+/**
+ * The messages here are read by somebody typing 24 words back in, so they say
+ * what is wrong rather than that something is.
+ */
+export declare function wordsToSeed(phrase: string): Uint8Array;

package/dist/seed-words.js

@@ -0,0 +1,64 @@
+import { entropyToMnemonic, mnemonicToEntropy, validateMnemonic, } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+/**
+ * The identity seed as 24 words, and back.
+ *
+ * Both apps had this, and a phrase written down from one has to restore on the
+ * other or it is worthless. They agreed — same wordlist, same BIP-39 calls, the
+ * same 24 — but they agreed by two people keeping two files in step, which is
+ * the arrangement this package exists to end.
+ *
+ * The standard 2048-word list is 11 bits a word: 256 bits of seed plus 8 bits of
+ * checksum makes 264, which is 24 words exactly. The checksum lives inside the
+ * words rather than beside them, so a mistyped or reordered phrase is rejected
+ * instead of quietly producing a different identity — and since no two words in
+ * the list share their first four letters, a misread word usually is not a word
+ * at all and fails before the checksum is reached.
+ *
+ * Only the encoding is borrowed from wallets. The key-stretching step they do on
+ * top is not wanted here: these 256 bits are the seed already, not a passphrase
+ * to grind into one.
+ */
+/** Length of the seed every local identity is calculated from. */
+export const SEED_BYTES = 32;
+/** How many words a backup is. Stated once so the message and the check agree. */
+export const BACKUP_WORDS = 24;
+/**
+ * Refuse a seed that cannot be one.
+ *
+ * The length check is the real one. The repeated-byte check is for a generator
+ * that has failed open and is handing back zeros, which is worth catching loudly
+ * rather than deriving a whole identity from.
+ */
+export function assertUsableSeed(seed) {
+    if (seed.length !== SEED_BYTES) {
+        throw new Error(`An identity seed is ${SEED_BYTES} bytes, not ${seed.length}.`);
+    }
+    const first = seed[0];
+    if (seed.every((b) => b === first)) {
+        throw new Error("Identity seed is a single repeated byte — the generator is broken.");
+    }
+}
+export function seedToWords(seed) {
+    assertUsableSeed(seed);
+    return entropyToMnemonic(seed, wordlist);
+}
+/**
+ * The messages here are read by somebody typing 24 words back in, so they say
+ * what is wrong rather than that something is.
+ */
+export function wordsToSeed(phrase) {
+    const normalised = phrase.trim().toLowerCase().split(/\s+/).join(" ");
+    if (!normalised)
+        throw new Error("Enter your identity words.");
+    const count = normalised.split(" ").length;
+    if (count !== BACKUP_WORDS) {
+        throw new Error(`That is ${count} words — an identity backup is ${BACKUP_WORDS}.`);
+    }
+    if (!validateMnemonic(normalised, wordlist)) {
+        throw new Error("Those words aren't a valid identity backup. Check for a mistyped or swapped word.");
+    }
+    const seed = mnemonicToEntropy(normalised, wordlist);
+    assertUsableSeed(seed);
+    return seed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gryt/crypto",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Message encryption for Gryt: key derivation, key bindings, sealed envelopes, pinning and comparison codes. Shared by the desktop client and the mobile app.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -33,7 +33,8 @@
   "dependencies": {
     "@noble/ciphers": "^2",
     "@noble/curves": "^2.3.0",
-    "@noble/hashes": "^2.3.0"
+    "@noble/hashes": "^2.3.0",
+    "@scure/bip39": "^2.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.33",