# puckk/ctfd-plugin-unique-token architecture

> Architecture diagram of the GitHub repository puckk/ctfd-plugin-unique-token, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/puckk/ctfd-plugin-unique-token
- Repository: https://github.com/puckk/ctfd-plugin-unique-token

## Overview

##### Project Type and Purpose
- This is a CTFd plugin (i.e. an extension module) whose job is to generate and persist a unique token per user, inject client-side code to replace placeholders in challenge descriptions, and expose HTTP endpoints for retrieving or using those tokens (e.g. auto-solving challenges via an admin endpoint).

##### Main Components
a. CTFd Core Application
- The primary Flask app that hosts user management, challenges, submissions, etc.
- Loads plugins via its plugin API.
b. Unique Token Plugin Module
- __init__.py: Python code that hooks into CTFd plugin lifecycle, defines database model for the token, registers two Flask blueprints:
– GET /get_user_token
– GET /admin-solve/<token>/<challenge_name>
- unique_token.js: Client-side script that replaces any `##unique_token##` placeholder in a challenge page with the logged‐in user’s token (fetched from the GET /get_user_token route).
c. Database
- A new table or model introduced by the plugin to store (user_id, token) records, using CTFd’s existing SQLAlchemy setup.
d. Browser (User)
- Renders challenge pages, executes unique_token.js to do string replacement.
- May call GET /get_user_token via AJAX.
e. Admin Client or Script
- Any HTTP client (curl, Python requests) that calls GET /admin-solve/<token>/<challenge_name> with a valid admin authorization token to auto-solve on a user’s behalf.

##### Interactions and Data Flow
1. User logs in to CTFd → Plugin login hook fires → Plugin generates a cryptographically secure token (using env vars: UNIQUE_TOKEN_SECRETKEY, UNIQUE_TOKEN_SALT) → Token is saved to the plugin’s DB table.
2. User views a challenge page → CTFd renders HTML → unique_token.js (injected by the plugin) executes in browser → It requests /get_user_token → Receives the token → Replaces all `##unique_token##` placeholders in the page.
3. Admin wants to solve a user’s challenge → Admin script calls /admin-solve/<user_token>/<challenge_name> with an Admin API token → Plugin verifies both tokens, finds the matching user, and uses CTFd’s internal API to mark the challenge as solved for that user.

##### Architectural Patterns & Principles
- Plugin architecture / modular extension of a monolithic Flask app
- MVC‐style separation within the plugin:
- Model: SQLAlchemy token table
- View/Controller: Flask blueprints for the two endpoints
- Client View: JS script executed in the browser
- Security by design: using environment variables for secrets, token hashing/salting

##### Technologies & Frameworks
- Python 3.9, Flask (via CTFd core)
- SQLAlchemy (through CTFd)
- JavaScript for client-side placeholder replacement
- RESTful endpoints for both front-end AJAX and admin scripts

- Components: Browser (User), CTFd Core, Unique Token Plugin (Python), unique_token.js (Client), Database, Admin Script.
- Notes on security: secret key & salt, admin token header.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        Browser(["Browser (User)"]):::external
    end

    %% CTFd Core
    subgraph "CTFd Core"
        CoreApp["Flask App"]:::core
        CTFdAPI["CTFd Internal API"]:::core
    end

    %% Plugin - Python Side
    subgraph "Plugin - Python Side"
        PluginInit["__init__.py"]:::plugin
        DBModel["Token Model (SQLAlchemy)"]:::plugin
    end

    %% Plugin - JS Side
    subgraph "Plugin - JS Side"
        UniqueJS["unique_token.js"]:::plugin
    end

    %% Storage
    Database[(Database)]:::storage

    %% Admin Script
    AdminScript[[Admin Script]]:::external

    %% Documentation
    subgraph "Documentation & Config"
        README["README.md"]:::plugin
        AllContrib[".all-contributorsrc"]:::plugin
        License["LICENSE"]:::plugin
    end

    %% Interactions
    Browser -->|login to CTFd| CoreApp
    CoreApp -->|"login hook"| PluginInit
    PluginInit -->|"generate token\n(SECRET & SALT)"| DBModel
    DBModel -->|persist token| Database

    Browser -->|views challenge page| CoreApp
    CoreApp -->|inject JS| UniqueJS
    UniqueJS -->|GET /get_user_token| PluginInit
    PluginInit -->|fetch token| DBModel
    DBModel -->|return token| PluginInit
    PluginInit -->|response token| UniqueJS
    UniqueJS -->|replace ##unique_token##| Browser

    AdminScript -->|GET /admin-solve/<token>/<challenge_name>| PluginInit
    PluginInit -->|verify admin token| CTFdAPI
    CTFdAPI -->|mark challenge solved| DBModel
    DBModel -->|update record| Database

    %% Click Events
    click PluginInit "https://github.com/puckk/ctfd-plugin-unique-token/blob/main/__init__.py"
    click UniqueJS "https://github.com/puckk/ctfd-plugin-unique-token/blob/main/unique_token.js"
    click README "https://github.com/puckk/ctfd-plugin-unique-token/blob/main/README.md"
    click AllContrib "https://github.com/puckk/ctfd-plugin-unique-token/blob/main/.all-contributorsrc"
    click License "https://github.com/puckk/ctfd-plugin-unique-token/tree/main/LICENSE"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef plugin fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef external fill:#FFD700,stroke:#333,stroke-width:1px
```
