Functional Weave
Code in TypeScript

auth.recovery-codes

Two-factor recovery codes: generate from caller entropy, hash for storage, and verify-and-consume as a pure step.

1.0.0 · published 2026-10-10 by charlie · Anterra

Pinned by 39 tests, run in TypeScript, Python and Rust.generateRecoveryCodes 11 · normaliseRecoveryCode 9 · hashRecoveryCode 8 · consumeRecoveryCode 11

What it does

Recovery (backup) codes for two-factor sign-in: the codes a user prints or saves when they turn on an authenticator app, and types in when the phone is lost. Four functions, all pure:

- `generateRecoveryCodes(entropy, count)` turns the caller's random bytes into codes like `7h3k-q9mz-2bxa-v0pd`. Show them to the user once. - `hashRecoveryCode(code)` is what you store instead of each code. - `consumeRecoveryCode(code, hashes)` takes what the user typed and the stored hashes still unused, and answers whether it matched and the hashes to store from now on (the matched one removed). - `normaliseRecoveryCode(code)` is the one form a typed code is read in.

The functions

A group: 4 functions that work together, each in its own file, each pinned by its own tests in TypeScript, Python and Rust. A project can install only the ones it calls.

  1. generateRecoveryCodes (entropy: int[], count: int) -> string[]
  2. normaliseRecoveryCode (code: string) -> string?
  3. hashRecoveryCode (code: string) -> string
  4. consumeRecoveryCode (code: string, hashes: string[]) -> RecoveryCheck

The type it declares, generated into your project

/** The answer to one recovery-code attempt, with the new stored set. */
export interface RecoveryCheck {
  /** the code matched one of the stored hashes */
  readonly valid: boolean;
  /** which stored hash it matched, when valid */
  readonly index: number | null;
  /** the hashes to store now: the matched one removed, order kept */
  readonly remaining: readonly string[];
}

Once installed, your code imports each one from the group's module.

generateRecoveryCodes throws on bad input 11 tests

export function generateRecoveryCodes(entropy: readonly number[], count: number): readonly string[]
entropyint[]random bytes from a CSPRNG, at least 10 per code; extra bytes are ignored
countinthow many codes, 1 to 50 (10 is usual)
returnsstring[]codes like 7h3k-q9mz-2bxa-v0pd, to show the user once and never store

For example

  • generateRecoveryCodes(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1) → 000g-40r4-0m30-e209 one code from bytes 0..9: 80 bits as 16 Crockford characters
  • generateRecoveryCodes(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1) → 0000-0000-0000-0000 all zero bytes are all zeros
  • generateRecoveryCodes(255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 1) → zzzz-zzzz-zzzz-zzzz all 0xff bytes are the last letter throughout
import { generateRecoveryCodes } from "#fune/auth.recovery-codes@^1";
impl/typescript/generate_recovery_codes.ts · 42 lines · open · raw
/** Crockford's base32 alphabet, lower case: no i, l, o or u to misread. */
export const RECOVERY_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";

const BYTES_PER_CODE = 10;

/**
 * Recovery codes from the caller's random bytes, 10 bytes (80 bits) each,
 * as 16 Crockford base32 characters in four groups. The randomness is an
 * argument so the function stays pure: pass bytes from a CSPRNG
 * (crypto.getRandomValues, secrets.token_bytes, getrandom), never Math.random.
 */
export function generateRecoveryCodes(entropy: readonly number[], count: number): readonly string[] {
  if (!Array.isArray(entropy)) throw new TypeError("entropy must be a list of integers from 0 to 255");
  for (const b of entropy) {
    if (typeof b !== "number" || !Number.isInteger(b) || b < 0 || b > 255) {
      throw new RangeError("entropy must be a list of integers from 0 to 255");
    }
  }
  if (typeof count !== "number" || !Number.isInteger(count) || count < 1 || count > 50) {
    throw new RangeError("count must be a whole number from 1 to 50");
  }
  const needed = count * BYTES_PER_CODE;
  if (entropy.length < needed) {
    throw new RangeError(`entropy must hold at least 10 bytes per code: ${needed} needed, ${entropy.length} given`);
  }
  const codes: string[] = [];
  for (let c = 0; c < count; c++) {
    let chars = "";
    let buffer = 0;
    let bits = 0;
    for (let i = 0; i < BYTES_PER_CODE; i++) {
      buffer = ((buffer << 8) | entropy[c * BYTES_PER_CODE + i]) & 0xffff;
      bits += 8;
      while (bits >= 5) {
        bits -= 5;
        chars += RECOVERY_ALPHABET[(buffer >> bits) & 31];
      }
    }
    codes.push(`${chars.slice(0, 4)}-${chars.slice(4, 8)}-${chars.slice(8, 12)}-${chars.slice(12, 16)}`);
  }
  return codes;
}

normaliseRecoveryCode 9 tests

export function normaliseRecoveryCode(code: string): string | null
codestringa code as the user typed it: any case, with or without hyphens and spaces
returnsstring?the 16 characters with i and l read as 1 and o as 0; null if it cannot be a code

For example

  • normaliseRecoveryCode(vtpv-xvr1-4d2p-f2db) → vtpvxvr14d2pf2db a generated code loses its hyphens
  • normaliseRecoveryCode( VTPV XVR1 4D2P F2DB ) → vtpvxvr14d2pf2db upper case and spaces as typed
  • normaliseRecoveryCode(IL0O-abcd-efgh-jkmn) → 1100abcdefghjkmn i and l read as 1, o read as 0
import { normaliseRecoveryCode } from "#fune/auth.recovery-codes@^1";
impl/typescript/normalise_recovery_code.ts · 21 lines · open · raw

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { RECOVERY_ALPHABET } from "./auth_recovery_codes_generate_recovery_codes.ts";  ← generateRecoveryCodes, another function of this group · built into the same file, even by a slim install

/**
 * A typed code in its one stored form: ASCII lower case, spaces and hyphens
 * dropped, and i/l read as 1 and o as 0 as Crockford's base32 says, so a
 * code read aloud or copied by hand still matches. Null when what is left is
 * not exactly 16 characters of the alphabet.
 */
export function normaliseRecoveryCode(code: string): string | null {
  if (typeof code !== "string") throw new TypeError("code must be a string");
  let out = "";
  for (const raw of code) {
    if (raw === " " || raw === "-") continue;
    let ch = raw >= "A" && raw <= "Z" ? String.fromCharCode(raw.charCodeAt(0) + 32) : raw;
    if (ch === "i" || ch === "l") ch = "1";
    else if (ch === "o") ch = "0";
    if (!RECOVERY_ALPHABET.includes(ch) || ch.length !== 1) return null;
    out += ch;
  }
  return out.length === 16 ? out : null;
}

hashRecoveryCode throws on bad input 8 tests

export function hashRecoveryCode(code: string): string
codestringa code as generated or as typed
returnsstringthe lowercase hex SHA-256 to store in place of the code

For example

  • hashRecoveryCode(vtpv-xvr1-4d2p-f2db) → ea9c4071abd35fa50aa34307961d4a3f2fb25f307daa10c1f78ce462ca3bb6e1 the stored hash of a generated code
  • hashRecoveryCode(VTPV XVR1 4D2P F2DB) → ea9c4071abd35fa50aa34307961d4a3f2fb25f307daa10c1f78ce462ca3bb6e1 typed differently, the same hash
  • hashRecoveryCode(0000-0000-0000-0000) → 90a768aff01cf5e1d699927179a2c82455a9428eca6669681709a10660672071 all zeros
import { hashRecoveryCode } from "#fune/auth.recovery-codes@^1";
impl/typescript/hash_recovery_code.ts · 16 lines · open · raw

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { sha256 } from "./crypto_sha256.ts";  ← from crypto.sha256 ^1.0.0 · built alongside by fune
import { hexEncode } from "./encoding_hex_hex_encode.ts";
import { utf8Encode } from "./encoding_utf8_utf8_encode.ts";
import { normaliseRecoveryCode } from "./auth_recovery_codes_normalise_recovery_code.ts";  ← normaliseRecoveryCode, another function of this group · built into the same file, even by a slim install

/**
 * What to store for a code: the hex SHA-256 of "fune.recovery-code:" and the
 * normalised code. A fast unsalted hash is enough because each code carries
 * 80 random bits; the prefix keeps these hashes apart from any other SHA-256
 * the app stores.
 */
export function hashRecoveryCode(code: string): string {
  const normal = normaliseRecoveryCode(code);
  if (normal === null) throw new Error("not a recovery code");
  return hexEncode(sha256(utf8Encode(`fune.recovery-code:${normal}`)));
}

consumeRecoveryCode throws on bad input 11 tests

export function consumeRecoveryCode(code: string, hashes: readonly string[]): RecoveryCheck
codestringwhat the user typed
hashesstring[]the user's stored hashes still unused
returnsRecoveryCheckwhether it matched, and the hashes to store from now on

For example

  • consumeRecoveryCode(000g-40r4-0m30-e209, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c38…) → valid true, index 0, remaining d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c3877d2d3dccdade4ecc8bf1581eadc97ded65bd0 the first code matches and is removed
  • consumeRecoveryCode(185G R38E 1W81 24GK, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c38…) → valid true, index 1, remaining 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, b80588adecc76b1a8269a92c3877d2d3dccdade4ecc8bf1581eadc97ded65bd0 the middle code, typed in capitals with spaces
  • consumeRecoveryCode(2gah-c5rr-34d1-p70x, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c38…) → valid true, index 2, remaining 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605 the last code leaves the first two
import { consumeRecoveryCode } from "#fune/auth.recovery-codes@^1";
impl/typescript/consume_recovery_code.ts · 30 lines · open · raw

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { type RecoveryCheck } from "./auth_recovery_codes_types.ts";
import { constantTimeEqual } from "./crypto_constant_time_equal.ts";  ← from crypto.constant-time-equal ^1.0.0 · built alongside by fune
import { hexDecode } from "./encoding_hex_hex_decode.ts";
import { normaliseRecoveryCode } from "./auth_recovery_codes_normalise_recovery_code.ts";  ← normaliseRecoveryCode, another function of this group · built into the same file, even by a slim install
import { hashRecoveryCode } from "./auth_recovery_codes_hash_recovery_code.ts";  ← hashRecoveryCode, another function of this group · built into the same file, even by a slim install

const HASH = /^[0-9a-f]{64}$/;

/**
 * One recovery-code attempt as a pure state change: the stored hashes in,
 * whether the code matched and the hashes to store from now on out. Every
 * stored hash is compared, in constant time, with no early exit, so the time
 * taken says nothing about which one matched. Write `remaining` back in the
 * same transaction that signs the user in, so a code works once.
 */
export function consumeRecoveryCode(code: string, hashes: readonly string[]): RecoveryCheck {
  if (!Array.isArray(hashes)) throw new TypeError("hashes must be a list of 64 lowercase hex characters each");
  for (const h of hashes) {
    if (typeof h !== "string" || !HASH.test(h)) throw new Error("hashes must be a list of 64 lowercase hex characters each");
  }
  if (normaliseRecoveryCode(code) === null) return { valid: false, index: null, remaining: hashes.slice() };
  const attempt = hexDecode(hashRecoveryCode(code));
  let index = -1;
  for (let i = 0; i < hashes.length; i++) {
    const same = constantTimeEqual(attempt, hexDecode(hashes[i]));
    if (same && index < 0) index = i;
  }
  if (index < 0) return { valid: false, index: null, remaining: hashes.slice() };
  return { valid: true, index, remaining: hashes.filter((_, i) => i !== index) };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 4 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add auth.recovery-codes

That builds the whole group. To build only what you call, and whatever it uses inside the group:

fune add auth.recovery-codes --only generateRecoveryCodes
Download for TypeScript auth.recovery-codes-1.0.0-typescript.fune · 25,677 bytes sha256 fc9ec695b13474447b5497c1892e19f8485e89895f154661a6ef2bb826f111ea

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./auth.recovery-codes-1.0.0-typescript.fune, or fetch it from a terminal with fune pull auth.recovery-codes@1.0.0:typescript.

The whole function, every language, is one file too: auth.recovery-codes-1.0.0.fune, 38,449 bytes, sha256 6ef8fcb7816b0dd00c753cfcdb1a93ee97b78be5f3118ec3641e47f3a77f011b. It installs into a project of any language.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

// fune: before auth.recovery-codes.generateRecoveryCodes
// fune: before auth.recovery-codes.normaliseRecoveryCode
// fune: before auth.recovery-codes.hashRecoveryCode
// fune: before auth.recovery-codes.consumeRecoveryCode

after — your function gets the result and the arguments, and returns the final result.

// fune: after auth.recovery-codes.generateRecoveryCodes
// fune: after auth.recovery-codes.normaliseRecoveryCode
// fune: after auth.recovery-codes.hashRecoveryCode
// fune: after auth.recovery-codes.consumeRecoveryCode

replace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.

// fune: replace crypto.constant-time-equal in auth.recovery-codes
// fune: replace crypto.sha256 in auth.recovery-codes
// fune: replace encoding.hex in auth.recovery-codes
// fune: replace encoding.utf8 in auth.recovery-codes

step — your function runs at a numbered point inside a function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show auth.recovery-codes --steps.

// fune: step auth.recovery-codes.<fn> after <n|label>

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.

generateRecoveryCodes 11 tests

CaseArgumentsExpected
one code from bytes 0..9: 80 bits as 16 Crockford characters 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1 → 000g-40r4-0m30-e209
all zero bytes are all zeros 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1 → 0000-0000-0000-0000
all 0xff bytes are the last letter throughout 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 1 → zzzz-zzzz-zzzz-zzzz
three codes take consecutive 10-byte slices in order 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 3 → 000g-40r4-0m30-e209, 185g-r38e-1w81-24gk, 2gah-c5rr-34d1-p70x
extra entropy past count*10 bytes is ignored 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 2 → 000g-40r4-0m30-e209, 185g-r38e-1w81-24gk
a mixed byte pattern 222, 173, 190, 239, 1, 35, 69, 103, 137, 171, 1 → vtpv-xvr1-4d2p-f2db
too few bytes for the count 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2 → error: entropy must hold at least 10 bytes per code: 20 needed, 19 given
a count of 0 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 → error: count must be a whole number from 1 to 50
a count over 50 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 4… → error: count must be a whole number from 1 to 50
a byte over 255 256, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1 → error: entropy must be a list of integers from 0 to 255
Show the other 1 test
CaseArgumentsExpected
a negative byte -1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1 → error: entropy must be a list of integers from 0 to 255

normaliseRecoveryCode 9 tests

CaseArgumentsExpected
a generated code loses its hyphens vtpv-xvr1-4d2p-f2db → vtpvxvr14d2pf2db
upper case and spaces as typed VTPV XVR1 4D2P F2DB → vtpvxvr14d2pf2db
i and l read as 1, o read as 0 IL0O-abcd-efgh-jkmn → 1100abcdefghjkmn
u is not in the alphabet uuuu-abcd-efgh-jkmn → —
15 characters is too short abcd-efgh-jkmn-pqr → —
17 characters is too long abcd-efgh-jkmn-pqrst → —
the empty string → —
a full-width letter is not ASCII and is refused abcd-efgh-jkmn-pqrs → —
a trailing newline is not whitespace we drop abcd-efgh-jkmn-pqrs → —

hashRecoveryCode 8 tests

CaseArgumentsExpected
the stored hash of a generated code vtpv-xvr1-4d2p-f2db → ea9c4071abd35fa50aa34307961d4a3f2fb25f307daa10c1f78ce462ca3bb6e1
typed differently, the same hash VTPV XVR1 4D2P F2DB → ea9c4071abd35fa50aa34307961d4a3f2fb25f307daa10c1f78ce462ca3bb6e1
all zeros 0000-0000-0000-0000 → 90a768aff01cf5e1d699927179a2c82455a9428eca6669681709a10660672071
o and l typed for 0 and 1 hash as the digits oooo-llll-0000-1111 → 84e30ba19fdce78656ac4fcaffe366f58a528c5739becb836ea1745575477ff4
the code from bytes 0..9 000g-40r4-0m30-e209 → 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497
a code of the wrong length abcd-efgh → error: not a recovery code
a code with u in it uuuu-abcd-efgh-jkmn → error: not a recovery code
the empty string → error: not a recovery code

consumeRecoveryCode 11 tests

CaseArgumentsExpected
the first code matches and is removed 000g-40r4-0m30-e209, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c38… → valid true, index 0, remaining d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c3877d2d3dccdade4ecc8bf1581eadc97ded65bd0
the middle code, typed in capitals with spaces 185G R38E 1W81 24GK, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c38… → valid true, index 1, remaining 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, b80588adecc76b1a8269a92c3877d2d3dccdade4ecc8bf1581eadc97ded65bd0
the last code leaves the first two 2gah-c5rr-34d1-p70x, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c38… → valid true, index 2, remaining 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605
a code already used is not in the set 000g-40r4-0m30-e209, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c3877d2d3dccdade4ecc8bf1581eadc97ded65bd0 → valid false, index —, remaining d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c3877d2d3dccdade4ecc8bf1581eadc97ded65bd0
the last remaining code empties the set 2gah-c5rr-34d1-p70x, b80588adecc76b1a8269a92c3877d2d3dccdade4ecc8bf1581eadc97ded65bd0 → valid true, index 0, remaining
no codes left 000g-40r4-0m30-e209, → valid false, index —, remaining
a malformed code is refused, not thrown not-a-code, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1a8269a92c3877d2d3dcc… → valid false, index —, remaining 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, b80588adecc76b1…
a duplicate stored hash: only the first is consumed 185g-r38e-1w81-24gk, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605, d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605 → valid true, index 0, remaining d6f24e147c01ca863e9fdc7b35bef9398eadd1bafd254fd933fc8dcb6d4ba605
a stored hash in upper case is refused 000g-40r4-0m30-e209, 02734A8CB7D9E671C0E80B3EEE14DC9AD421B0BB87D15A6FEF52F8F121AAB497 → error: hashes must be a list of 64 lowercase hex characters each
a stored hash of the wrong length is refused 000g-40r4-0m30-e209, abc → error: hashes must be a list of 64 lowercase hex characters each
Show the other 1 test
CaseArgumentsExpected
a stored hash with a trailing newline is refused 000g-40r4-0m30-e209, 02734a8cb7d9e671c0e80b3eee14dc9ad421b0bb87d15a6fef52f8f121aab497 → error: hashes must be a list of 64 lowercase hex characters each

Verification

Verified by the operator, not the sandbox 39 test vectors declared; none run by the registry.

Verified locally by the registry's operator, not by the sandbox. This version was published with FUNE_VERIFY_MODE=inline-dev (the operator's import of the first-party registry, or a development server): the server validated the package - its manifest, signatures, imports, safety lint and test rules - but the registry did not run its test vectors in its sandbox. The operator runs them with `fune verify --all` before importing.

Signed by the registry with key fw-9dc887227da47575 (ed25519), over its integrity and this report's digest. The full report · JSON

More from the author

## Randomness comes from you

The function never reads a random source, so it can be pinned by test vectors. Pass bytes from a cryptographically secure generator, 10 per code: `crypto.getRandomValues(new Uint8Array(100))` in TypeScript, `list(secrets.token_bytes(100))` in Python, `getrandom` in Rust. Never `Math.random` or Python's `random`. Bytes past `count * 10` are ignored.

## The codes

Each code is 10 random bytes (80 bits) written as 16 characters of Crockford's base32 alphabet (`0-9` and `a-z` without `i`, `l`, `o` and `u`), in four groups of four. When a code is typed back, case, spaces and hyphens do not matter, and `i`/`l` are read as `1` and `o` as `0`, so a code copied by hand still works. Only ASCII is accepted: a full-width or other-script letter makes the code invalid in every language.

## Why a fast, unsalted hash is enough

Passwords need a slow, salted hash (see `auth.password-hash`) because people choose guessable ones. These codes are not chosen: each is 80 bits from a CSPRNG, so even with the stored hashes in hand an attacker faces 2^80 SHA-256 guesses per code, which is out of reach. A salt would add nothing against that. The hash is SHA-256 of `fune.recovery-code:` followed by the normalised code, in lowercase hex; the prefix keeps these hashes apart from any other SHA-256 values the app stores. This holds only because the codes are random: do not use these functions for codes a person makes up.

## Consuming a code

`consumeRecoveryCode` compares the attempt with every stored hash in constant time, with no early exit, so the time taken does not reveal which one matched. On a match, `remaining` is the stored list without that hash, in the same order; write it back in the same transaction that signs the user in, so a code works once even under two concurrent requests (use a row lock or a compare-and-set on the old list). A malformed code is `valid: false` with the list unchanged, not an error, since it is ordinary user input. A stored entry that is not 64 lowercase hex characters is an error: it means the stored data is corrupt.

Rate-limit attempts as you would logins (`auth.login-throttle`). Ten codes is the usual set; let the user regenerate the whole set, which replaces the stored hashes.

Files

PathBytes
README.md2,947
impl/python/consume_recovery_code.py1,566
impl/python/generate_recovery_codes.py1,603
impl/python/hash_recovery_code.py619
impl/python/normalise_recovery_code.py925
impl/rust/consume_recovery_code.rs2,773
impl/rust/generate_recovery_codes.rs2,379
impl/rust/hash_recovery_code.rs976
impl/rust/normalise_recovery_code.rs1,148
impl/typescript/consume_recovery_code.ts1,641
impl/typescript/generate_recovery_codes.ts1,747
impl/typescript/hash_recovery_code.ts755
impl/typescript/normalise_recovery_code.ts912
vectors.json11,046