# TOTP diagnostic tool

- Human page: https://happytails.ai/en/developer-tools/totp-diagnostic-tool/
- Markdown: https://happytails.ai/en/developer-tools/totp-diagnostic-tool.md
- Structured JSON: https://happytails.ai/agents/en/developer-tools/totp-diagnostic-tool/index.json
- Visibility: public

## Tool capabilities

| Property | Value |
| --- | --- |
| Tool ID | `totp-diagnostic-tool` |
| Category | developer-tools |
| Implementation | Registered implementation. Registration alone is not a production-quality guarantee. |
| Browser execution | Use the visible action or interactive controls. |
| Browser processing | Browser; see tool notes for network behavior. |
| HTTP API | Not callable through HTTP. |
| Browser-agent interface | run_current_tool |

### Implementation notes

Runs in your browser and never exports the secret. Settings in an otpauth URI take priority; up to 20 steps are checked on each side of the time you enter.

### Inputs and settings

Text input: Secret or otpauth URI.

Example or placeholder shown in the interface (not a validated fixture):

```text
GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
```

Paste the Base32 secret or the otpauth:// link from your two-factor setup. Up to 4,096 characters. Review the settings before running.

| Setting | Meaning | Control type | Default | Constraints |
| --- | --- | --- | --- | --- |
| `time` | Evaluation time (UTC or Unix seconds) | text | "2026-10-16T12:00:00Z" |  |
| `observedCode` | Code the app shows (optional) | text | "" |  |
| `algorithm` | Hash algorithm | select | "SHA1" | Allowed: SHA1, SHA256, SHA512 |
| `digits` | Digits | number | "6" | min=6 max=8 step=1 |
| `period` | Time step in seconds | number | "30" | min=1 max=3600 step=1 |
| `window` | Steps to check on each side | number | "2" | min=0 max=20 step=1 |

### Browser-agent workflow

1. Open the human page in a browser that supports WebMCP.
2. Discover the interface exposed by that page; use its actual schema.
3. Select files on the page first when the tool requires files.
4. Call `run_current_tool` with valid input and settings.
5. Inspect the returned result or error and the displayed output. Retrieve files from the displayed download links.

Calls do not automatically copy or download results. Browser permissions still apply. Interface availability alone is not proof of successful execution.

### Planning specification

Input is one Base32 secret or otpauth URI of up to 4096 characters decoding to 1 to 128 bytes. The time must fall between 1970-01-01T00:00:00Z and 9999-12-31T23:59:59Z. The observed code has 6 to 8 digits and at most 32 characters including spaces. Up to 20 steps are checked on each side, with 6 to 8 digits and steps of 1 to 3600 seconds. Everything runs locally in your browser. Download a JSON report and a CSV of codes per time step.

This describes intended requirements. Use the implementation notes, interface schema and observed output to determine current support.

### Complete machine-readable capability record

```json
{
  "id": "totp-diagnostic-tool",
  "category": "developer-tools",
  "built": true,
  "requirements": "Input is one Base32 secret or otpauth URI of up to 4096 characters decoding to 1 to 128 bytes. The time must fall between 1970-01-01T00:00:00Z and 9999-12-31T23:59:59Z. The observed code has 6 to 8 digits and at most 32 characters including spaces. Up to 20 steps are checked on each side, with 6 to 8 digits and steps of 1 to 3600 seconds. Everything runs locally in your browser. Download a JSON report and a CSV of codes per time step.",
  "implementation": {
    "fields": [
      {
        "key": "time",
        "label": "Evaluation time (UTC or Unix seconds)",
        "value": "2026-10-16T12:00:00Z",
        "type": "text"
      },
      {
        "key": "observedCode",
        "label": "Code the app shows (optional)",
        "value": "",
        "type": "text"
      },
      {
        "key": "algorithm",
        "label": "Hash algorithm",
        "value": "SHA1",
        "type": "select",
        "values": [
          "SHA1",
          "SHA256",
          "SHA512"
        ]
      },
      {
        "key": "digits",
        "label": "Digits",
        "value": "6",
        "type": "number",
        "min": 6,
        "max": 8,
        "step": 1
      },
      {
        "key": "period",
        "label": "Time step in seconds",
        "value": "30",
        "type": "number",
        "min": 1,
        "max": 3600,
        "step": 1
      },
      {
        "key": "window",
        "label": "Steps to check on each side",
        "value": "2",
        "type": "number",
        "min": 0,
        "max": 20,
        "step": 1
      }
    ],
    "registrationFamily": "crypto-formats-reference",
    "inputMaxLength": 4096,
    "inputErrorCode": "CRYPTO_FORMATS_REFERENCE_TOO_LONG",
    "note": "Runs in your browser and never exports the secret. Settings in an otpauth URI take priority; up to 20 steps are checked on each side of the time you enter.",
    "experience": {
      "automatic": false,
      "single": true,
      "inputMaxLength": 4096,
      "inputMode": "text",
      "label": "Secret or otpauth URI",
      "placeholder": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",
      "help": "Paste the Base32 secret or the otpauth:// link from your two-factor setup. Up to 4,096 characters. Review the settings before running.",
      "action": null
    },
    "mode": "explicit",
    "interactive": false
  },
  "execution": "Browser interface",
  "api": null,
  "browser_agent": {
    "supported": true,
    "name": "run_current_tool",
    "discovery": "WebMCP on the human page in a supporting browser",
    "verification": "See audit/API-AUDIT.md; availability is not verification"
  }
}
```

## Page guide

Check why an authenticator code is rejected by listing TOTP codes around a time you choose. Paste a Base32 secret or otpauth URI and see which time step, if any, matches the code your app shows.

How can we improve this tool?

Report a problem or share an idea.

Please leave out private information. Your message and the tool name go to our team via PostHog.

### How to use TOTP diagnostic tool

1. Paste the Base32 secret or the full otpauth URI from your setup screen.
2. Enter the evaluation time in UTC, or Unix seconds, and the code your app shows.
3. Check the algorithm, digits and time step, or let the otpauth URI set them.
4. Run the tool and read which offset matches to see the clock drift.

## Useful next steps

- [Password generator](https://happytails.ai/en/privacy-tools/password-generator/) ([Markdown](https://happytails.ai/en/privacy-tools/password-generator.md))

- [HMAC generator](https://happytails.ai/en/developer-tools/hmac-generator/) ([Markdown](https://happytails.ai/en/developer-tools/hmac-generator.md))

- [QR code reader](https://happytails.ai/en/business-tools/qr-code-reader/) ([Markdown](https://happytails.ai/en/business-tools/qr-code-reader.md))

## What it computes

Codes follow RFC 6238 (TOTP, May 2011) using the HOTP truncation from RFC 4226 (December 2005). The time step counter is the Unix time divided by the step length, rounded down. The tool lists codes for each step on both sides of the time you enter and marks the step that matches your observed code.

### Reading the result

A match at offset 0 means the clocks agree. A match at another offset means one clock is that many steps fast or slow. No match usually means a different secret, algorithm or digit count.

### Assumptions and limits

The time is never taken from your device clock; you enter it so results can be reproduced. The secret stays in the page and is not written to the report. Secrets shorter than 16 bytes are flagged as weak. If the last character of the secret leaves spare bits that are not zero, they are dropped the way authenticator apps do and the report sets secretTrailingBitsIgnored to true. The observed code may be grouped with spaces, as apps show it.