Plan a Safe TOTP Authenticator Flow

A six-digit authenticator code works offline because the phone and server share a secret and calculate the same short-lived value from time. The implementation is small. The recovery and replay rules are where products get hurt.

This guide belongs to reel R085. Comment TOTP for the matching module and runnable starter.

Define the boundary before building

Input: account identifier, issuer name, secret storage policy, allowed clock drift, replay policy, recovery method, rate limits, and enrollment state.

Output: an enrollment plan, server verification contract, recovery flow, replay controls, test vectors, and security review questions.

The starter keeps exact checks in code and gives Claude only the reviewable drafting work. Dry-run is the default. Live mode can call Anthropic's Messages API, but it still returns a draft and performs no external action.

Paste this boundary into Claude Code before asking for implementation:

Workflow: Plan a Safe TOTP Authenticator Flow
Input: account identifier, issuer name, secret storage policy, allowed clock drift, replay policy, recovery method, rate limits, and enrollment state
Output: an enrollment plan, server verification contract, recovery flow, replay controls, test vectors, and security review questions

Map the trigger, strict input fields, deterministic code checks, Claude drafting step, approval gate, failure queue, and saved evidence. Use null for missing facts. Do not change code or call an external service yet.

The modules that matter

Enrollment

Generate the secret on the server, protect it at rest, encode issuer and account labels in the enrollment URI, and show it once. Do not enable TOTP until the user proves enrollment with a valid code.

Verification

Use a maintained TOTP implementation. Compare codes in constant time where practical, allow only a narrow clock window, rate-limit attempts, and remember an accepted time step so the same code cannot be replayed.

Recovery

Issue hashed single-use recovery codes, let the user regenerate them after strong authentication, and notify the account when TOTP or recovery settings change. Support must not become a weaker bypass.

Rules worth keeping beside the code

Generate and store TOTP secrets only on the trusted server boundary.
Show the enrollment secret once and require a valid code before activation.
Use a narrow clock window and block replay within an accepted time step.
Provide single-use recovery codes with the same protection as passwords.

The dangerous version is logging shared secrets, accepting unlimited drift, trusting client-side verification, allowing code replay, or creating recovery paths that bypass authentication. The pack deliberately stops at a draft so a person can inspect those boundaries before enabling anything real.

Test the ugly paths

Published TOTP vectors pass.
Current time step succeeds once.
Expired and future-window codes fail.
Accepted code cannot be replayed.
Rate limit activates.
Every recovery code works once and is then rejected.

The final verification is concrete: Check published TOTP test vectors, test adjacent time steps and replay rejection, and complete enrollment and recovery with fictional accounts only.

Use this prompt to turn the evidence into acceptance tests:

Design tests for Plan a Safe TOTP Authenticator Flow using only the attached fictional fixtures.
Cover the normal path, missing input, malformed input, a repeated event, a permission failure, a dependency failure, and the named safety boundary.
For each test return: input, expected state, prohibited side effect, and evidence to save.
Do not execute external actions.

Run the pack locally

The ZIP is a complete Node 22 starter with no third-party npm dependency. It includes an importable n8n webhook, Docker Compose, GitHub Actions validation and manual-run workflows, deterministic samples, and tests.

npm test
npm run validate
npm run sample
cp .env.example .env
docker compose up --build

Only set WORKFLOW_MODE=live, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL after the dry-run output and tests make sense for your system. Keep real secrets in the environment, never in the n8n export.

Download the runnable pack

Start with the fictional dry-run. It validates the input and returns a reviewable draft without changing code, production data, customer accounts, or an external service.

Before enabling a real action

Replace every fictional fixture, assign the approval owner, define the duplicate key, set a timeout and retry rule, and save the original evidence. Then test one failure on purpose. If the workflow cannot stop visibly and replay safely, it is not ready to act.