API

Public surface of Bip39Chiper-TS (bip39chiper on npm). Only high-level functions are exported — no raw deriveKey / token helpers.

import {
  obfuscate,
  recover,
  createSession,
  normalizeToken,
  isWellFormedToken,
  parseExport,
  formatExport,
  Bip39ChiperError,
  ALPHABET,
  TOKEN_LENGTH,
  VERSION,
  SALT_UTF8,
  DEFAULT_ITERATIONS,
  DEFAULT_KEY_BYTES,
  MIN_PASSWORD_LENGTH,
} from "bip39chiper";

Types

type KeyBytes = 16 | 32 | 64;
type WordCount = 12 | 15 | 18 | 21 | 24;

type Params = {
  iterations: number;
  keyBytes: KeyBytes;
};

type ExportMeta = {
  version?: string;
  words?: number;
  iterations?: number;
  keyBytes?: number;
  tokens: string[];
};

Defaults when params is omitted: iterations = 600_000, keyBytes = 32.

obfuscate

function obfuscate(
  mnemonic: string[] | string,
  password: string,
  params?: Partial<Params>
): Promise<string[]>;

• Accepts a word array or a whitespace-separated string (words lowercased).
• Returns tokens in mnemonic order.
• Rejects unknown BIP-39 words and invalid word counts.

recover

function recover(
  tokens: string[],
  password: string,
  wordCount: WordCount,
  params?: Partial<Params>
): Promise<string[]>;

• Token order does not matter.
• Builds a session internally, recovers, then clears it.
• Validates BIP-39 checksum when all slots are filled.

createSession

function createSession(
  password: string,
  wordCount: WordCount,
  params?: Partial<Params>
): Promise<Session>;

type Session = {
  readonly wordCount: WordCount;
  readonly params: Params;
  obfuscate(mnemonic: string[] | string): Promise<string[]>;
  recover(tokens: string[]): Promise<string[]>;
  clear(): void;
};

Eager: on create, runs PBKDF2 and builds the full N×2048 lookup table once. Use for repeated recoveries. Call clear() when done.

In browsers, prefer a Web Worker for createSession / heavy recover.

Tokens

function normalizeToken(raw: string): string;
function isWellFormedToken(raw: string): boolean;

Normalization: uppercase, keep only alphabet characters. Well-formed = length 9 after normalize.

Export

function parseExport(text: string): ExportMeta;
function formatExport(
  tokens: string[],
  meta: { words: number; iterations: number; keyBytes: number }
): string;

Interchange format matches the macOS app. See algorithm spec §10.

Password policy

Product rule (same as the reference app), applied on obfuscate / recover / createSession:

Condition	Error code
Empty string	empty_password
Length < 8	password_too_short

Errors

All thrown errors are Bip39ChiperError with a stable code:

Code	When
invalid_word_count	N ∉
unknown_word	Word not in BIP-39 English list
invalid_token_format	Token not well-formed after normalize
token_not_found	Absent from lookup table (wrong password / garbage)
ambiguous_token	Cannot pick a unique free slot
slot_conflict	Slot already holds a different word
invalid_bip39_checksum	Full phrase fails BIP-39 checksum
empty_password	Password length 0
password_too_short	Password length < 8
session_cleared	Method called after session.clear()

Ambiguous tokens are never guessed.

Constants

Export	Value
VERSION	"v1"
SALT_UTF8	"Bip39Chiper.v1.positional-hasher"
ALPHABET	23456789ABCDEFGHJKMNPQRSTVWXYZ
TOKEN_LENGTH	9
DEFAULT_ITERATIONS	600_000
DEFAULT_KEY_BYTES	32
MIN_PASSWORD_LENGTH	8