@varnir/signing 0.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License (MIT)
+Copyright (c) 2026 Adam Walker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @varnir/signing
+
+Key management for Varnir wallets: generate and validate BIP39 recovery
+phrases, derive a secp256k1 key pair from one, and import an already-known
+private key. This package derives and validates key material — it never
+sends a key anywhere. All signing and derivation happen locally, in the
+caller's own process; nothing here talks to a network.
+
+## Custody model
+
+Everything in this package operates on key material the caller already
+holds in memory. There is no server component, no remote call, and no
+place a private key or recovery phrase is transmitted. A recovery phrase
+generated here, or a private key derived or imported through it, exists
+only for as long as the calling process keeps it — what you do with it
+afterwards (store it, hand it to a signer, discard it) is entirely up to
+the caller. Treat both recovery phrases and private keys as bearer secrets:
+anyone who has one can spend from the wallet it derives.
+
+## Install
+
+```bash
+npm install @varnir/signing
+```
+
+## Usage
+
+```ts
+import {
+  generateRecoveryPhrase,
+  isValidRecoveryPhrase,
+  derivePrivateKeyFromPhrase,
+  keyPairFromPrivateKeyHex,
+} from '@varnir/signing';
+
+const phrase = generateRecoveryPhrase();       // 12-word BIP39 phrase
+isValidRecoveryPhrase(phrase);                 // true
+
+const {privateKeyHex, publicKeyHex} = derivePrivateKeyFromPhrase(phrase);
+
+// Or start from an already-known private key instead of a phrase:
+const keyPair = keyPairFromPrivateKeyHex('0x...');
+```
+
+- **`generateRecoveryPhrase()`** — a fresh 12-word (128-bit entropy) BIP39
+  mnemonic, from the standard English wordlist.
+- **`isValidRecoveryPhrase(phrase)`** / **`normalizeRecoveryPhrase(phrase)`**
+  — validate or normalize (trim, lower-case, collapse whitespace) a phrase
+  before using it.
+- **`derivePrivateKeyFromPhrase(phrase)`** — BIP32/BIP44 HD derivation
+  (`m/44'/1'/0'/0/0`) from the phrase's BIP39 seed, returning a secp256k1
+  key pair as `0x`-prefixed hex.
+- **`recoverySeedFromPhrase(phrase)`** — the raw 64-byte BIP39 seed itself,
+  for callers (such as `@varnir/chain-client`) that derive other key types
+  from the same seed.
+- **`keyPairFromPrivateKeyHex(hex)`** / **`isPrivateKeyHex(value)`** —
+  derive the matching public key from an already-known private key, or
+  check that a string looks like one, without generating anything new.
+
+Built on audited, widely-used primitives: [`@noble/curves`](https://www.npmjs.com/package/@noble/curves)
+for secp256k1, [`@scure/bip32`](https://www.npmjs.com/package/@scure/bip32)
+for HD derivation, and [`bip39`](https://www.npmjs.com/package/bip39) for
+mnemonic generation/validation. Ships as compiled ESM with type
+declarations.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export declare const RECOVERY_PHRASE_LENGTH = 12;
+export type KeyPair = {
+    privateKeyHex: string;
+    publicKeyHex: string;
+};
+export declare function normalizeRecoveryPhrase(phrase: string): string;
+export declare function generateRecoveryPhrase(): string;
+export declare function isValidRecoveryPhrase(phrase: string): boolean;
+export declare function isPrivateKeyHex(value: string): boolean;
+/**
+ * The raw 64-byte BIP39 seed for a recovery phrase: `mnemonicToSeedSync` of the
+ * normalized phrase, validated first. This is the ONE seed step every key type
+ * derives from - the secp256k1 HD key below, and the post-quantum keys derived
+ * in `@varnir/chain-client`'s `deriveKeyPairFromPhrase` (which domain-separates
+ * by key type on top of this same seed). It is exported so that PQ derivation
+ * reuses this exact step rather than duplicating `bip39.mnemonicToSeedSync`.
+ *
+ * Returned as a plain `Uint8Array` (not a Node `Buffer`) so a consumer without
+ * Node builtins - a browser, a Worker - can use it.
+ */
+export declare function recoverySeedFromPhrase(phrase: string): Uint8Array;
+export declare function derivePrivateKeyFromPhrase(phrase: string): KeyPair;
+export declare function keyPairFromPrivateKeyHex(value: string): KeyPair;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,MAAM,MAAM,OAAO,GAAG;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAmBF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAMjE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAWlE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAa/D"}

package/dist/index.js

@@ -0,0 +1,93 @@
+// Secure signing tools — key management and transaction signing used by the wallet apps and SDK.
+//
+// BIP39/HD derivation ported from apps/wallet-mobile/src/wallet/keys.ts,
+// where it's already proven to run inside the Expo/React Native runtime
+// (a strictly harder environment than a browser - no Node builtins either
+// way) - not reimplemented, just given a shared home so scanner-web's
+// mini-wallet doesn't duplicate it a third time. wallet-mobile's own copy
+// is untouched; nothing here is wired up to import from this package yet.
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { HDKey } from '@scure/bip32';
+import * as bip39 from 'bip39';
+/**
+ * BIP44: purpose 44' / coin type 1' / account 0' / external chain / first address.
+ * Coin type 1' is the registered "all testnets" slot; the ledger engine has no
+ * registered coin type of its own and this build talks to no chain, so 1' keeps
+ * the keys off any production coin's derivation space.
+ */
+const DERIVATION_PATH = "m/44'/1'/0'/0/0";
+/** 128 bits of entropy — a 12 word phrase. */
+const ENTROPY_BITS = 128;
+const WORDLIST = bip39.wordlists.english;
+export const RECOVERY_PHRASE_LENGTH = 12;
+function toPrefixedHex(bytes) {
+    let out = '';
+    for (const byte of bytes) {
+        out += byte.toString(16).padStart(2, '0');
+    }
+    return `0x${out}`;
+}
+function fromPrefixedHex(value) {
+    const body = value.slice(2);
+    const bytes = new Uint8Array(body.length / 2);
+    for (let i = 0; i < bytes.length; i += 1) {
+        bytes[i] = Number.parseInt(body.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+export function normalizeRecoveryPhrase(phrase) {
+    return phrase.trim().toLowerCase().split(/\s+/).join(' ');
+}
+export function generateRecoveryPhrase() {
+    return bip39.generateMnemonic(ENTROPY_BITS, undefined, WORDLIST);
+}
+export function isValidRecoveryPhrase(phrase) {
+    return bip39.validateMnemonic(normalizeRecoveryPhrase(phrase), WORDLIST);
+}
+export function isPrivateKeyHex(value) {
+    return /^0x[0-9a-fA-F]{64}$/.test(value.trim());
+}
+/**
+ * The raw 64-byte BIP39 seed for a recovery phrase: `mnemonicToSeedSync` of the
+ * normalized phrase, validated first. This is the ONE seed step every key type
+ * derives from - the secp256k1 HD key below, and the post-quantum keys derived
+ * in `@varnir/chain-client`'s `deriveKeyPairFromPhrase` (which domain-separates
+ * by key type on top of this same seed). It is exported so that PQ derivation
+ * reuses this exact step rather than duplicating `bip39.mnemonicToSeedSync`.
+ *
+ * Returned as a plain `Uint8Array` (not a Node `Buffer`) so a consumer without
+ * Node builtins - a browser, a Worker - can use it.
+ */
+export function recoverySeedFromPhrase(phrase) {
+    const normalized = normalizeRecoveryPhrase(phrase);
+    if (!bip39.validateMnemonic(normalized, WORDLIST)) {
+        throw new Error('That recovery phrase is not valid.');
+    }
+    return Uint8Array.from(bip39.mnemonicToSeedSync(normalized));
+}
+export function derivePrivateKeyFromPhrase(phrase) {
+    const seed = recoverySeedFromPhrase(phrase);
+    const child = HDKey.fromMasterSeed(seed).derive(DERIVATION_PATH);
+    if (!child.privateKey || !child.publicKey) {
+        throw new Error('Could not derive a key from that recovery phrase.');
+    }
+    return {
+        privateKeyHex: toPrefixedHex(child.privateKey),
+        publicKeyHex: toPrefixedHex(child.publicKey),
+    };
+}
+export function keyPairFromPrivateKeyHex(value) {
+    const trimmed = value.trim();
+    if (!isPrivateKeyHex(trimmed)) {
+        throw new Error('Enter a 64-character hex key prefixed with 0x.');
+    }
+    const privateKeyHex = trimmed.toLowerCase();
+    try {
+        const publicKey = secp256k1.getPublicKey(fromPrefixedHex(privateKeyHex), true);
+        return { privateKeyHex, publicKeyHex: toPrefixedHex(publicKey) };
+    }
+    catch {
+        throw new Error('That key is not a valid secp256k1 private key.');
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E;AAC1E,0EAA0E;AAE1E,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAE1C,8CAA8C;AAC9C,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC;AAEzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAOzC,SAAS,aAAa,CAAC,KAAiB;IACtC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,GAAG,EAAE,CAAC;AACpB,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,CAAC,gBAAgB,CAAC,YAAY,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,OAAO,KAAK,CAAC,gBAAgB,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,MAAM,UAAU,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACnD,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACjE,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IAED,OAAO;QACL,aAAa,EAAE,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC;QAC9C,YAAY,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,SAAS,CAAC,YAAY,CAAC,eAAe,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,CAAC;QAC/E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@varnir/signing",
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "Secure signing tools — key management and transaction signing used by the wallet apps and SDK.",
+  "$comment": "Ships COMPILED output (dist) for the same reason @varnir/chain-client does, and as a precondition of it: chain-client's built dist/index.js imports this package by name, so if this one still resolved to raw .ts, chain-client's build would be unloadable outside a TS-aware bundler - exactly the case shipping dist exists to serve. ESM to match chain-client; src/ has no relative imports, so nothing here needed .js extensions.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Varnir/varnir.git",
+    "directory": "packages/signing"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.4"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.0",
+    "@scure/bip32": "^1.7.0",
+    "bip39": "^3.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@varnir/tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "echo \"no lint configured yet\"",
+    "clean": "rm -rf dist"
+  }
+}