Seeded two-factor backup code generator

Supply a count and a secret seed, and the same inputs always produce the same ordered set. That repeatability is useful for controlled provisioning, test fixtures, documented recovery workflows, and systems that need to reconstruct codes without storing a generated list. Generation is local computation only: it uses no network call, clock, random source, account data, or hidden state. Treat the seed and every resulting code as sensitive authentication material.

Choose the count and protect the seed

Start by choosing how many recovery codes the account or application should issue. The count must be an integer from one through one thousand; a request below one is rejected instead of silently producing an empty set. Then provide a non-empty seed. The seed is the complete source of reproducibility, so identical seed and count values produce identical codes in identical order. Use a long, high-entropy secret created and stored through your organization’s approved secret-management process. A person’s name, email address, project label, or short memorable phrase is not an appropriate production seed because another person may guess it and reconstruct the codes. Do not reuse one seed across users, environments, or services. Domain separation inside the algorithm prevents accidental overlap with unrelated derivations, but it cannot compensate for a weak or exposed seed. If you need repeatable fixtures for automated tests, clearly label and isolate test seeds so their output can never be accepted by a production authentication system. The seed is limited to 4,096 characters to keep execution bounded and predictable.

Understand the deterministic generation process

Each output position is derived independently with SHA-256 from a versioned label, the exact seed length, the seed text, the zero-based position, and a retry counter. Including the seed length makes the input framing unambiguous, while the versioned label separates this purpose from other seeded calculations. The generator reads unsigned values from the digest and uses rejection sampling before reducing them to eight decimal digits. That rejection step avoids the small distribution bias that direct modulo conversion would introduce. It formats every accepted number as two groups of four digits separated by a hyphen, preserving leading zeroes. A set tracks values already emitted; if a collision occurs, the retry counter is advanced deterministically until a new code is found. Therefore the result contains the requested number of unique codes, and rerunning the same request recreates the same collision decisions as well as the same final list. No network service, system clock, runtime random generator, persisted cache, or mutable module state can influence the answer. Changing even one seed character normally changes the entire list.

Deploy, store, and invalidate codes safely

Generation is only one part of a backup-code workflow. Your authentication service must store an approved verifier for each code, mark a code consumed after its first successful use, rate-limit attempts, and provide a deliberate revocation or regeneration action. Never log the seed or plain codes in analytics, traces, support tickets, build output, or shared chat. Deliver codes to the authenticated user through a protected session and encourage offline storage in a password manager or another secure location. Determinism makes disaster recovery and controlled provisioning easier, but it also means anyone who obtains the seed can reconstruct every code. Rotate to a new independent seed whenever exposure is suspected, when a user requests regeneration, or when policy requires invalidating the old set. Do not merely request a different count with the old seed: positions shared by both requests remain the same. The grouped digits improve transcription but provide only one hundred million possible values per code, so online defenses remain essential. The API costs $0.002 per request; the browser path uses the same pure computation.