Features

| | | |---|---| | Obfuscate | BIP-39 English mnemonic → position-bound 9-character codes | | Recover | Paste codes in any order · password → original phrase | | Session | Eager lookup table for repeated recoveries without re-deriving | | Export | Compatible .txt headers (version, words, iterations, keyBytes) | | Cross-runtime | Pure TypeScript · Node ≥ 18 · browsers | | Conformance | Official test vectors (~649 cases) |

Install

npm install bip39chiper

Package name on npm: bip39chiper. Product name: Bip39Chiper-TS.
Repository: li-nd/bip39-chiper-ts.

Security note

Bip39Chiper-TS is obfuscation, not encryption. Anyone who has both the password and the codes can recover the mnemonic. Keep them separate. Verify recovery before destroying originals. It is not a hardware wallet replacement.

Read Security and the shared product notes on chiper.developer.pm/security.

Quick start

import { obfuscate, recover } from "bip39chiper";

const mnemonic = [
  "abandon", "abandon", "abandon", "abandon",
  "abandon", "abandon", "abandon", "abandon",
  "abandon", "abandon", "abandon", "about",
];

const password = "testpassword";
const params = { iterations: 100_000, keyBytes: 32 as const };

const tokens = await obfuscate(mnemonic, password, params);
// → ["3JKDEPFPN", "2MKGTQMA4", …]

const restored = await recover([...tokens].reverse(), password, 12, params);
// → same mnemonic (token order does not matter)

Session (eager lookup table)

recover builds an N×2048 token table after PBKDF2. For repeated work with the same password and word count:

import { createSession } from "bip39chiper";

const session = await createSession(password, 24, params);
// PBKDF2 + full lookup table built once

const words = await session.recover(tokens);
await session.obfuscate(mnemonic);
session.clear(); // drop key + table from memory

In browsers, run createSession / recover inside a Web Worker so the UI stays responsive (default PBKDF2 is 600 000 iterations).

Defaults

| Parameter | Default | |-----------|---------| | iterations | 600_000 | | keyBytes | 32 (16 | 32 | 64) | | Word counts | 12, 15, 18, 21, 24 | | Token length | 9 (alphabet radix 30) | | Min password | 8 characters |

Export format

Compatible with the macOS app interchange format:

# version: v1
# words: 24
# iterations: 600000
# keyBytes: 32
TOKEN1 TOKEN2 ... TOKENN

import { formatExport, parseExport } from "bip39chiper";

const text = formatExport(tokens, {
  words: 12,
  iterations: 100_000,
  keyBytes: 32,
});

const parsed = parseExport(text);

Password is never written to the file.

Documentation

| Resource | URL | |----------|-----| | Library docs | ts.chiper.developer.pm | | Browser demo | demo.chiper.developer.pm (separate repository) | | API | Public surface, sessions, errors | | Security | Threat model notes for the library | | Conformance | Submodule, test:fast vs full suite | | Algorithm specification | Normative format v1 (also online) |

macOS product docs: chiper.developer.pm.

Related

• Bip39Chiper — offline macOS app (reference UI)
• bip39-chiper-test-vectors — machine-readable v1 vectors

License

MIT © Markus Lind