# hannah-portswigger/totpauthenticate architecture

> Architecture diagram of the GitHub repository hannah-portswigger/totpauthenticate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hannah-portswigger/totpauthenticate
- Repository: https://github.com/hannah-portswigger/totpauthenticate

## Overview

##### Project type and purpose
- This is a Burp Suite Enterprise Edition extension, written in Java, that implements a session-handling action to generate and inject TOTP (time-based one-time password) tokens into outgoing HTTP requests based on user-defined rules.

##### File structure
- build.gradle / gradlew: the Gradle build & packaging scripts (produces a “fatJar” JAR).
- src/main/java/burp: core Burp extension classes
- MySessionHandlingAction.java – implements the Burp session-handling rule action interface.
- TOTPAuthenticate.java – generates the OTP and applies it to a request.
- src/main/java/userinterface:
- UserInterface.java – handles any UI dialogs or parameter collection inside Burp.
- src/main/java/utils: helper classes
- ConfigurationParser.java – parses the rule string (the /^^…^^/ syntax).
- RuleType.java – enum for HEADER, URL, COOKIE, BODY_PARAM, BODY_REGEX.
- Utilities.java – TOTP generation and common helpers.
- documentation: supporting GIF and docs for usage.

##### Key insights from README
- Extension registers itself with Burp’s session-handling API.
- Users define a session-handling rule whose “description” field encodes the TOTP secret, rule type, and parameter name.
- The extension parses that description at runtime, generates a TOTP code on each request, and injects it per the rule.
- Built using Gradle; loaded via Burp Enterprise’s extension loader.

##### Detail
- Break the extension into as many logical components as you see in the file tree (three packages + build artifact).
- Session-handling rule JSON/config as a data artifact.
- How changes to the rule require a reload of the extension in Burp.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host System
    subgraph "Burp Suite Enterprise Host"
        BURP["Burp Suite Enterprise"]:::host
        ENGINE["Extension Loader & Session Handling Engine"]:::host
    end

    BURP -->|"loads extension"| ENGINE

    %% Extension JAR and Modules
    subgraph "TOTP Authenticate Extension (fat JAR)" 
        subgraph "Registration Layer"
            A["MySessionHandlingAction\n(Registration Layer)"]:::ext
        end
        subgraph "Core Logic"
            B["TOTPAuthenticate\n(OTP generator & injector)"]:::ext
        end
        subgraph "UI Module"
            C["UserInterface\n(UI Layer)"]:::ext
        end
        subgraph "Utilities & Parsing"
            D["ConfigurationParser"]:::util
            E["RuleType Enum"]:::util
            F["Utilities"]:::util
        end
    end

    %% Data and External
    Config["Session Handling Rule\n(JSON description)"]:::data
    HB["HTTP Request Builder"]:::ext
    TARGET["Target Server"]:::external

    %% Build, Docs, Metadata
    Build["Build & Packaging Scripts"]:::build
    Docs["Documentation & Usage Guides"]:::docs
    Metadata["Project Metadata & License"]:::docs

    %% Connections
    ENGINE -->|"load & register MySessionHandlingAction"| A
    ENGINE -->|"onRequest callback"| A
    A -->|"parse secretKey, ruleType, parameterName"| D
    A -->|"generate OTP"| B
    B -->|"inject into request via Builder"| HB
    HB -->|"send HTTP Request"| TARGET
    TARGET -->|"HTTP Response"| ENGINE
    Config -->|"provides rule description"| D
    C -->|"prompt for configuration"| ENGINE

    %% Click Events
    click A "https://github.com/hannah-portswigger/totpauthenticate/blob/main/src/main/java/burp/MySessionHandlingAction.java"
    click B "https://github.com/hannah-portswigger/totpauthenticate/blob/main/src/main/java/burp/TOTPAuthenticate.java"
    click C "https://github.com/hannah-portswigger/totpauthenticate/blob/main/src/main/java/userinterface/UserInterface.java"
    click D "https://github.com/hannah-portswigger/totpauthenticate/blob/main/src/main/java/utils/ConfigurationParser.java"
    click E "https://github.com/hannah-portswigger/totpauthenticate/blob/main/src/main/java/utils/RuleType.java"
    click F "https://github.com/hannah-portswigger/totpauthenticate/blob/main/src/main/java/utils/Utilities.java"
    click Build "https://github.com/hannah-portswigger/totpauthenticate/blob/main/build.gradle"
    click Docs "https://github.com/hannah-portswigger/totpauthenticate/tree/main/documentation/"
    click Metadata "https://github.com/hannah-portswigger/totpauthenticate/blob/main/README.md"

    %% Styles
    classDef host fill:#dddddd,stroke:#333,stroke-width:1px
    classDef ext fill:#a8d0e6,stroke:#333,stroke-width:1px
    classDef util fill:#98c379,stroke:#333,stroke-width:1px
    classDef data fill:#c0c0c0,stroke:#333,stroke-width:1px
    classDef external fill:#fcae1e,stroke:#333,stroke-width:1px
    classDef build fill:#c292ea,stroke:#333,stroke-width:1px
    classDef docs fill:#d28ea6,stroke:#333,stroke-width:1px
```
