cryptils

Utilities around Spectre / Master Password Algorithm (by Maarten Billemont), implemented in TypeScript, using Noble & Scure cryptography by @paulmillr. Used for deriving stateless accounts & passwords, 2fa, shamir secret sharing, crypto/bitcoin/nostr public and private keys, and more.

Highlights

• Don't store, derive! Derive passwords and keys from a master password and a name
• Cloud-less & storage-less password manager, stateless password derivation
• Uses only audited Noble & Scure cryptography by @paulmillr
• TypeScript implementation of Spectre.app / Master Password Algorithm by Maarten Billemont
• Stateless account & password derivation - no need to store anything
• Stateless wallet/keys derivation for Ethereum, Bitcoin, Litecoin, Vertcoin, Nostr
• Support for splitting the secret key with Shamir Secret Sharing scheme
• AES-256-GCM encrypt/decrypt a private thing using the secret key
• Generate and validate 2FA tokens (HOTP & TOTP)
  • RFC 4226 & RFC 6238
  • support SHA-1, SHA-256, SHA-512 hashing algorithms
  • support different digits lengths, up to 10

Install

npm add cryptils
bun add cryptils
deno add npm:cryptils

Usage

1import { deriveCryptoKeys, spectreV4 } from 'cryptils/derive';
2
3// personal name (can be anything), master password, account name (or site url + handle)
4const wgw = spectreV4('some persona', 'fool master pawdy', 'twitter.com/wgw_eth');
5const keys = deriveCryptoKeys(wgw.secret);
6
7console.log('privkey', bytesToHex(wgw.secret));
8console.log('wiggle account:', wgw);
9// => { secret: uint8array, persona: string, securepass: string, account: string }
10
11console.log('crypto keys:', keys);
12// => { bitcoin, nostr, ethereum, litecoin, vertcoin }

or using separate functions, to save on computation

1import { deriveBitcoinKeys, deriveEthereumKeys, deriveNostrKeys, spectreV4 } from 'cryptils/derive';
2
3const wgw = spectreV4('some persona', 'fool master pawdy', 'twitter.com/wgw_eth');
4
5console.log('btc1', deriveBitcoinKeys(wgw.secret));
6console.log('btc2', deriveBitcoinKeys(randomBytes(32)));
7// => { mnemonic, salt, privkey, pubkey, address }
8
9console.log('eth', deriveEthereumKeys(wgw.secret));
10// => { mnemonic, salt, privkey, pubkey, address }
11
12console.log('nostr', deriveNostrKeys(wgw.secret));
13// => { mnemonic salt, privkey, pubkey, npub, nsec, nrepo }

Docs

Example with 2FA OTP

1import {
2  getHotp,
3  getOtpSecret,
4  getTokenUri,
5  getTotp,
6  parseOtpSecret,
7  validateHotp,
8  validateTotp,
9} from 'cryptils/otp';
10import qrcode from 'qrcode';
11
12// accepts secret uint8array, secret as base32 string, or hex string,
13// if not passed anything it will generate random secret
14const secret = getOtpSecret();
15const token = await getTotp(secret, { digits: 8, algorithm: 'SHA-512' });
16const valid = await validateTotp(secret, token, { digits: 8, algorithm: 'SHA-512' });
17
18console.log({ secret, token, valid });
19
20const hotp = await getHotp(secret);
21console.log({ hotp, valid: await validateHotp(secret, hotpToken) });
22
23const parsedSecret = parseOtpSecret('5DXDAFF6BALL25TOYZXJHDCW4LY4OWTH');
24const uri = getTokenUri(secret, { issuer: 'MyApp', username: 'barry' });
25cosole.log({ parsedSecret, uri });
26
27console.log(await qrcode.toString(uri));

Example with AES-256-GCM

1import { decryptWithSecret, encryptWithSecret } from 'cryptils/aes';
2import { spectreV4 } from 'cryptils/derive';
3import { randomBytes } from 'cryptils/utils';
4
5const account = spectreV4('usrname', 'foo pass bar', 'twt.com');
6
7// or try with random one
8const secret = randomBytes(32);
9
10console.log({ account });
11
12const encrypted = await encryptWithSecret(account.securepass, account.secret);
13const decrypted = await decryptWithSecret(encrypted, account.secret);
14
15console.log({ encrypted, decrypted, same: decrypted === account.securepass });

Types

1export type SpectreOptions = { template?: string; hash?: any; iterations?: number };
2export type SpectreResult = { secret: Uint8Array; name: string; user: string; pass: string };
3
4export type HexString = string;
5export type Input = Uint8Array | string;
6export type SecretKey = Uint8Array | HexString;
7export type HashAlgo = 'SHA-1' | 'SHA-256' | 'SHA-512' | string;
8export type TokenResult = string;

LICENSE

SPDX-License-Identifier: MPL-2.0