From be5efc8815c39241e3db6b79aa9147bc73522f20 Mon Sep 17 00:00:00 2001
From: AYDEV-FR <aymeric.deliencourt@aydev.fr>
Date: Sun, 21 Jun 2026 17:12:08 +0200
Subject: [PATCH] feat(integrations): add CTFd plugin for Dploy environments

Add a CTFd plugin that lets players start/stop/extend/check an on-demand
Dploy environment directly from the challenge view.

Rather than a custom challenge type, any standard challenge becomes a Dploy
challenge when its Connection Info is a Dploy run URL
(e.g. https://dploy.example.com/run/<template>); the plugin parses the API
base + template from it server-side and injects a Start/Refresh/Extend/Stop
panel into the challenge modal.

Auth uses a BFF model: the browser only calls same-origin proxy routes; the
plugin obtains a CTFd-issued id_token for the player via a trusted,
auto-approved OIDC auth-code+PKCE bounce against CTFd's own provider (the
companion ctfd-oidc-provider plugin), caches it server-side, and forwards it
to Dploy as a Bearer token. Aligning the client id with Dploy's JWT_AUDIENCE
(dploy) and requesting the profile scope (name claim) means no auth problem
appears.

Also includes a docker-compose test stack: CTFd with both plugins plus a mock
Dploy API that validates tokens against CTFd's JWKS exactly like real Dploy,
exercising the full auth + proxy + UI path without a Kubernetes cluster.

Claude-Session: https://claude.ai/code/session_01M4Dd5oASBGHwr6ts6wTnYn
---
 integrations/ctfd_dploy/README.md             | 152 +++++++++++
 integrations/ctfd_dploy/__init__.py           | 242 +++++++++++++++++
 integrations/ctfd_dploy/assets/dploy.css      |  65 +++++
 integrations/ctfd_dploy/assets/dploy.js       | 251 ++++++++++++++++++
 integrations/ctfd_dploy/config.json           |   4 +
 integrations/ctfd_dploy/dploy_client.py       |  68 +++++
 integrations/ctfd_dploy/oidc.py               | 224 ++++++++++++++++
 integrations/ctfd_dploy/requirements.txt      |   2 +
 integrations/testing/Dockerfile.ctfd          |  32 +++
 integrations/testing/README.md                |  92 +++++++
 integrations/testing/docker-compose.yml       |  70 +++++
 integrations/testing/dploy-mock/Dockerfile    |  10 +
 integrations/testing/dploy-mock/app.py        | 147 ++++++++++
 .../testing/dploy-mock/requirements.txt       |   4 +
 integrations/testing/oidc_apps.yaml           |  20 ++
 15 files changed, 1383 insertions(+)
 create mode 100644 integrations/ctfd_dploy/README.md
 create mode 100644 integrations/ctfd_dploy/__init__.py
 create mode 100644 integrations/ctfd_dploy/assets/dploy.css
 create mode 100644 integrations/ctfd_dploy/assets/dploy.js
 create mode 100644 integrations/ctfd_dploy/config.json
 create mode 100644 integrations/ctfd_dploy/dploy_client.py
 create mode 100644 integrations/ctfd_dploy/oidc.py
 create mode 100644 integrations/ctfd_dploy/requirements.txt
 create mode 100644 integrations/testing/Dockerfile.ctfd
 create mode 100644 integrations/testing/README.md
 create mode 100644 integrations/testing/docker-compose.yml
 create mode 100644 integrations/testing/dploy-mock/Dockerfile
 create mode 100644 integrations/testing/dploy-mock/app.py
 create mode 100644 integrations/testing/dploy-mock/requirements.txt
 create mode 100644 integrations/testing/oidc_apps.yaml

diff --git a/integrations/ctfd_dploy/README.md b/integrations/ctfd_dploy/README.md
new file mode 100644
index 0000000..2a3653b
--- /dev/null
+++ b/integrations/ctfd_dploy/README.md
@@ -0,0 +1,152 @@
+# CTFd → Dploy plugin
+
+A [CTFd](https://ctfd.io) plugin that lets players **start, stop, extend and
+check** an on-demand [Dploy](https://docs.dploy.dev) environment **directly from
+the challenge view** — no separate Dploy login, no copy-pasting tokens.
+
+It pairs with the companion
+[`ctfd-oidc-provider`](https://github.com/AYDEV-FR/ctfd-oidc-provider) plugin:
+CTFd is the **OIDC Provider** of Dploy, so a CTFd-issued token is exactly what
+Dploy's API trusts. The plugin obtains one for the logged-in player behind the
+scenes and forwards it to Dploy.
+
+## How a challenge becomes a "Dploy challenge"
+
+There is **no custom challenge type**. Any standard challenge becomes a Dploy
+challenge when its **Connection Info** is a Dploy *run URL*:
+
+```
+https://dploy.example.com/run/<template>
+```
+
+The plugin parses this into the Dploy API base (`https://dploy.example.com`) and
+the template name (`<template>`), and injects a control panel into that
+challenge's modal:
+
+```
+Environment
+[ Healthy ]  expires in 42 min
+https://alice-ab12cd.dploy.example.com
+[ Start ] [ Refresh ] [ Extend ] [ Stop ]
+```
+
+The detection pattern is configurable (`DPLOY_URL_PATTERN`); the default is
+
+```
+^(?<base>https?://[^/]+)/run/(?<template>[^/?#\s]+)
+```
+
+(written once in JS-regex syntax and reused on both sides). The connection URL
+is only ever parsed **server-side** from the challenge's stored Connection Info,
+so a player can never aim their token at an arbitrary host.
+
+## Auth model (BFF)
+
+```
+ Browser ──same-origin──▶ CTFd plugin proxy ──Bearer id_token──▶ Dploy API
+   │                          │
+   │  (no token ever          └─ trusted OIDC auth-code+PKCE bounce
+   │   reaches the page)          against CTFd's own provider, cached
+   │                              in the server-side Flask session
+```
+
+* The challenge panel calls **same-origin** routes
+  (`/plugins/ctfd_dploy/challenges/<id>/{start,status,extend,stop}`), gated by
+  CTFd's normal session auth and CSRF.
+* The proxy needs a Dploy token for the player. It runs a standard
+  Authorization-Code + PKCE flow against CTFd's own `/oauth/authorize`. Because
+  the OAuth client is registered **trusted**, a logged-in player is
+  auto-approved and bounced straight back — a brief, consent-free popup. The
+  resulting `id_token` is cached in the **server-side** session and never
+  exposed to JavaScript.
+* When the token expires (or Dploy rejects it), the next action silently
+  re-bounces.
+
+`start`→`GET /api/run/{t}` (create-or-get), `status`→`GET …/status`,
+`extend`→`POST …/extend`, `stop`→`DELETE /api/run/{t}` on Dploy.
+
+## Why "no auth problems"
+
+Dploy validates the token's `iss`, `aud` and username claim. Make the plugin's
+client match what Dploy expects and everything just works:
+
+| Dploy setting (default)        | Plugin requirement                                  |
+|--------------------------------|-----------------------------------------------------|
+| `JWT_ISSUER`                   | `DPLOY_OIDC_ISSUER` = same CTFd provider issuer      |
+| `JWT_AUDIENCE` (`dploy`)       | `DPLOY_OIDC_CLIENT_ID` = same value (`dploy`)        |
+| `JWT_USERNAME_CLAIM` (`name`)  | request the `profile` scope (default) so `name` is present |
+
+Both sides verify against the **same CTFd JWKS** (`/oauth/jwks`), so signatures
+always check out.
+
+## Install
+
+1. Copy this folder into your CTFd install as `CTFd/plugins/ctfd_dploy`
+   (the directory name must be `ctfd_dploy`), or mount it there. For the OCI /
+   Kubernetes pattern, copy it next to the `oidc_provider` plugin.
+2. Install the dependency: `pip install -r requirements.txt` (just `requests`).
+3. Restart CTFd. The plugin serves its assets and routes under
+   `/plugins/ctfd_dploy/…`.
+
+## Register the OAuth client (in the OIDC provider plugin)
+
+In **Admin → Plugins → OIDC Apps → Register application** (or via the provider's
+declarative `OIDC_PROVIDER_APPS_FILE`), create/extend the **`dploy`** client:
+
+* **Client type:** Confidential
+* **Trusted:** ✅ (so the bounce is auto-approved — no consent screen)
+* **Scopes:** `openid profile email`
+* **Redirect URIs:** add
+  `https://<your-ctfd-host>/plugins/ctfd_dploy/auth/callback`
+  (this is *in addition* to Dploy's own `/auth/callback`; reusing the same
+  `dploy` client id keeps the token `aud` aligned with Dploy)
+
+Declarative example (`oidc_apps.yaml`):
+
+```yaml
+apps:
+  - name: Dploy
+    client_id: dploy
+    client_secret: "<shared-with-dploy-and-this-plugin>"
+    type: confidential
+    trusted: true
+    scopes: [openid, profile, email]
+    redirect_uris:
+      - https://ctfd.example.com/auth/callback                       # Dploy SPA
+      - https://ctfd.example.com/plugins/ctfd_dploy/auth/callback     # this plugin
+    grant_types: [authorization_code, refresh_token]
+```
+
+## Configuration
+
+Set via environment variables (preferred) or CTFd `app.config`:
+
+| Variable                 | Default                          | Purpose |
+|--------------------------|----------------------------------|---------|
+| `DPLOY_OIDC_CLIENT_ID`   | `dploy`                          | Must equal Dploy's `JWT_AUDIENCE`. |
+| `DPLOY_OIDC_CLIENT_SECRET` | —                              | Secret of the confidential client above. |
+| `DPLOY_OIDC_ISSUER`      | provider's `OIDC_PROVIDER_ISSUER`, else request host | OIDC issuer to discover/authorize against. |
+| `DPLOY_OIDC_SCOPES`      | `openid profile email`           | Must include `profile` (for the `name` claim). |
+| `DPLOY_OIDC_REDIRECT_URI`| derived from the request host    | Override if CTFd is behind a proxy with a different external URL. |
+| `DPLOY_URL_PATTERN`      | `^(?<base>https?://[^/]+)/run/(?<template>[^/?#\s]+)` | JS-regex (named groups `base`, `template`) that marks a challenge as Dploy. |
+| `DPLOY_API_URL`          | — (derived from each URL)        | If set, acts as an **allowlist**: connection URLs must point at this host, and this host is used as the API base. |
+
+## Authoring a challenge
+
+Create an ordinary challenge and set its **Connection Info** to the Dploy run
+URL for the template, e.g. `https://dploy.example.com/run/web-pwn-01`. Save. The
+Start/Stop/Extend/Status controls appear automatically in the challenge modal.
+The `web-pwn-01` `DployTemplate` must exist and be enabled in Dploy.
+
+## Compatibility & notes
+
+* Targets **CTFd 3.6.x / 3.7.x** with the bundled `core` theme. The panel is
+  injected by observing the challenge modal and reading
+  `CTFd._internal.challenge.data`; the modal-body selectors are defensive, but a
+  heavily customized theme may need a tweak in `assets/dploy.js`
+  (`findModalBody`).
+* The plugin adds **no database tables** and defines no models — it only reads
+  the standard `connection_info` field.
+* Serve CTFd over **HTTPS** in production (the OAuth bounce and cookies assume
+  it). For local HTTP testing the provider needs `AUTHLIB_INSECURE_TRANSPORT=1`.
+```
diff --git a/integrations/ctfd_dploy/__init__.py b/integrations/ctfd_dploy/__init__.py
new file mode 100644
index 0000000..a8bfb5c
--- /dev/null
+++ b/integrations/ctfd_dploy/__init__.py
@@ -0,0 +1,242 @@
+# Copyright the Dploy authors.
+# SPDX-License-Identifier: MIT
+"""
+Dploy plugin for CTFd.
+
+Rather than adding a new challenge type, this plugin treats *any* standard
+challenge as a Dploy challenge when its **connection info** is a Dploy run URL,
+e.g.::
+
+    https://dploy.example.com/run/podinfo
+
+Such challenges get Start / Status / Extend / Stop controls injected into the
+challenge modal. From the connection URL the plugin derives both the Dploy API
+base (``https://dploy.example.com``) and the template name (``podinfo``).
+
+Auth model (BFF / Backend-For-Frontend):
+
+  * The browser only ever talks to *this* plugin's same-origin proxy routes,
+    gated by CTFd's normal session auth — no Dploy token ever reaches the page.
+  * Server-side, the proxy fetches a CTFd-issued id_token for the user via a
+    trusted (auto-approved) OIDC auth-code+PKCE bounce against CTFd's own
+    provider, caches it in the Flask session, and forwards it to Dploy as a
+    Bearer token. See ``oidc.py``.
+
+The connection URL is resolved to (base, template) **server-side** from the
+challenge's stored ``connection_info`` — never from a client-supplied value —
+so a user cannot point their token at an arbitrary host.
+
+Targets CTFd 3.6.x / 3.7.x with the bundled ``core`` theme. See README.md.
+"""
+
+import re
+from urllib.parse import urlsplit
+
+from flask import (
+    Blueprint, jsonify, redirect, render_template_string, request, session,
+)
+
+from CTFd.models import Challenges
+from CTFd.plugins import (
+    register_plugin_assets_directory,
+    register_plugin_script,
+    register_plugin_stylesheet,
+)
+from CTFd.utils.decorators import authed_only
+
+from .dploy_client import DployClient, DployError
+from . import oidc
+
+PLUGIN_ID = "ctfd_dploy"
+ASSETS = "/plugins/%s/assets/" % PLUGIN_ID
+
+# Default detection pattern, written in JS-regex syntax (named groups `base` and
+# `template`) so the same string can drive both the in-browser test and the
+# server-side parse. Override with the DPLOY_URL_PATTERN env var / app config.
+DEFAULT_PATTERN = r"^(?<base>https?://[^/]+)/run/(?<template>[^/?#\s]+)"
+
+
+def url_pattern():
+    return oidc.cfg("DPLOY_URL_PATTERN", DEFAULT_PATTERN)
+
+
+def _python_regex():
+    # Python's `re` spells named groups `(?P<name>...)`, JS spells them
+    # `(?<name>...)`. Translate so admins can configure one pattern.
+    return re.compile(url_pattern().replace("(?<", "(?P<"))
+
+
+def parse_connection_info(connection_info):
+    """Return ``(base_url, template)`` for a Dploy connection URL, else ``None``.
+
+    ``base`` defaults to scheme+host of the matched URL but a custom pattern may
+    capture it explicitly; ``template`` is required.
+    """
+    if not connection_info:
+        return None
+    m = _python_regex().search(connection_info.strip())
+    if not m:
+        return None
+    groups = m.groupdict()
+    template = (groups.get("template") or "").strip()
+    if not template:
+        return None
+    base = (groups.get("base") or "").strip()
+    if not base:
+        parts = urlsplit(connection_info.strip())
+        if parts.scheme and parts.netloc:
+            base = "%s://%s" % (parts.scheme, parts.netloc)
+    # An explicit DPLOY_API_URL acts as an allowlist: when set, the derived host
+    # must match it, otherwise we refuse to forward the user's token.
+    allow = (oidc.cfg("DPLOY_API_URL") or "").strip()
+    if allow:
+        if urlsplit(base).netloc and urlsplit(base).netloc != urlsplit(allow).netloc:
+            return None
+        base = allow
+    if not base:
+        return None
+    return base.rstrip("/"), template
+
+
+# --- Proxy blueprint --------------------------------------------------------
+
+dploy_bp = Blueprint("dploy", __name__)
+
+
+def _client_or_auth_error(base):
+    """Return (client_factory_base, None) when authed, else (None, response)."""
+    token = oidc.current_token()
+    if not token:
+        login_url = "/plugins/%s/auth/login?popup=1" % PLUGIN_ID
+        return None, (jsonify({"success": False, "error": "auth_required",
+                               "login_url": login_url}), 401)
+    return DployClient(base, token), None
+
+
+def _run(action, cid):
+    challenge = Challenges.query.filter_by(id=cid).first()
+    if challenge is None:
+        return jsonify({"success": False, "error": "unknown challenge"}), 404
+
+    resolved = parse_connection_info(getattr(challenge, "connection_info", None))
+    if resolved is None:
+        return jsonify({"success": False,
+                        "error": "this challenge is not a Dploy challenge"}), 400
+    base, template = resolved
+
+    client, err = _client_or_auth_error(base)
+    if err is not None:
+        return err
+
+    try:
+        data = getattr(client, action)(template)
+        return jsonify({"success": True, "data": data})
+    except DployError as e:
+        # A 401 from Dploy means our cached token is no longer accepted; drop it
+        # so the next call re-bounces through the provider.
+        if e.status == 401:
+            oidc.clear_token()
+            login_url = "/plugins/%s/auth/login?popup=1" % PLUGIN_ID
+            return jsonify({"success": False, "error": "auth_required",
+                            "login_url": login_url}), 401
+        msg = e.payload.get("error") if isinstance(e.payload, dict) else str(e.payload)
+        return jsonify({"success": False, "error": msg, "status": e.status}), e.status
+    except Exception as e:  # network / unexpected
+        return jsonify({"success": False, "error": "Dploy request failed: %s" % e}), 502
+
+
+@dploy_bp.route("/plugins/ctfd_dploy/config", methods=["GET"])
+def config():
+    # Lets the injected script know the detection pattern (kept in one place).
+    return jsonify({"pattern": url_pattern()})
+
+
+@dploy_bp.route("/plugins/ctfd_dploy/challenges/<int:cid>/start", methods=["POST"])
+@authed_only
+def start(cid):
+    return _run("start", cid)
+
+
+@dploy_bp.route("/plugins/ctfd_dploy/challenges/<int:cid>/status", methods=["GET"])
+@authed_only
+def status(cid):
+    return _run("status", cid)
+
+
+@dploy_bp.route("/plugins/ctfd_dploy/challenges/<int:cid>/extend", methods=["POST"])
+@authed_only
+def extend(cid):
+    return _run("extend", cid)
+
+
+@dploy_bp.route("/plugins/ctfd_dploy/challenges/<int:cid>/stop", methods=["POST"])
+@authed_only
+def stop(cid):
+    return _run("stop", cid)
+
+
+# --- OIDC bounce routes -----------------------------------------------------
+
+@dploy_bp.route("/plugins/ctfd_dploy/auth/login", methods=["GET"])
+@authed_only
+def auth_login():
+    next_url = request.args.get("next", "/challenges")
+    popup = request.args.get("popup") == "1"
+    try:
+        url = oidc.begin_login(next_url=next_url, popup=popup)
+    except Exception as e:
+        return _auth_result_page(ok=False, popup=popup, next_url=next_url,
+                                 message="Could not start Dploy login: %s" % e)
+    return redirect(url)
+
+
+@dploy_bp.route("/plugins/ctfd_dploy/auth/callback", methods=["GET"])
+@authed_only
+def auth_callback():
+    flow = session.get(oidc.SESSION_FLOW) or {}
+    popup = bool(flow.get("popup"))
+    next_url = flow.get("next", "/challenges")
+    try:
+        flow = oidc.complete_login(request)
+        popup = bool(flow.get("popup"))
+        next_url = flow.get("next", "/challenges")
+    except Exception as e:
+        return _auth_result_page(ok=False, popup=popup, next_url=next_url,
+                                 message="Dploy login failed: %s" % e)
+    return _auth_result_page(ok=True, popup=popup, next_url=next_url,
+                             message="Connected to Dploy.")
+
+
+# Minimal page shown after the OIDC bounce: in popup mode it notifies the opener
+# and closes; otherwise it redirects back to where the user came from.
+_AUTH_PAGE = """<!doctype html><html><head><meta charset="utf-8">
+<title>Dploy</title></head><body style="font-family:sans-serif;padding:2rem">
+<p>{{ message }}</p>
+<script>
+  var ok = {{ 'true' if ok else 'false' }};
+  var popup = {{ 'true' if popup else 'false' }};
+  var next = {{ next_url|tojson }};
+  if (popup && window.opener) {
+    try { window.opener.postMessage(
+      {type: "dploy-auth", ok: ok}, window.location.origin); } catch (e) {}
+    window.close();
+  } else {
+    setTimeout(function(){ window.location = next; }, ok ? 300 : 2500);
+  }
+</script>
+</body></html>"""
+
+
+def _auth_result_page(ok, popup, next_url, message):
+    return render_template_string(_AUTH_PAGE, ok=ok, popup=popup,
+                                  next_url=next_url, message=message)
+
+
+# --- Plugin entrypoint ------------------------------------------------------
+
+def load(app):
+    register_plugin_assets_directory(app, base_path=ASSETS)
+    # Injected into every themed page; it decorates Dploy challenges in-place.
+    register_plugin_script(ASSETS + "dploy.js")
+    register_plugin_stylesheet(ASSETS + "dploy.css")
+    app.register_blueprint(dploy_bp)
diff --git a/integrations/ctfd_dploy/assets/dploy.css b/integrations/ctfd_dploy/assets/dploy.css
new file mode 100644
index 0000000..75caab6
--- /dev/null
+++ b/integrations/ctfd_dploy/assets/dploy.css
@@ -0,0 +1,65 @@
+/* Copyright the Dploy authors. SPDX-License-Identifier: MIT */
+.dploy-panel {
+  margin-top: 1rem;
+  padding: 0.85rem 1rem;
+  border: 1px solid rgba(127, 127, 127, 0.35);
+  border-radius: 6px;
+}
+.dploy-panel .dploy-head {
+  font-weight: 600;
+  margin-bottom: 0.4rem;
+}
+.dploy-panel .dploy-state {
+  margin-bottom: 0.35rem;
+}
+.dploy-panel .dploy-badge {
+  display: inline-block;
+  padding: 0.1rem 0.5rem;
+  border-radius: 999px;
+  background: rgba(80, 160, 120, 0.18);
+  font-size: 0.85em;
+}
+.dploy-panel .dploy-exp {
+  margin-left: 0.5rem;
+  opacity: 0.75;
+  font-size: 0.85em;
+}
+.dploy-panel .dploy-link {
+  margin-bottom: 0.5rem;
+  word-break: break-all;
+}
+.dploy-panel .dploy-actions {
+  display: flex;
+  gap: 0.4rem;
+  flex-wrap: wrap;
+}
+.dploy-panel .dploy-btn {
+  padding: 0.3rem 0.75rem;
+  border: 1px solid rgba(127, 127, 127, 0.4);
+  border-radius: 4px;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.dploy-panel .dploy-btn:hover:not(:disabled) {
+  background: rgba(127, 127, 127, 0.12);
+}
+.dploy-panel .dploy-btn:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+.dploy-panel .dploy-start {
+  border-color: rgba(80, 160, 120, 0.6);
+}
+.dploy-panel .dploy-stop {
+  border-color: rgba(200, 90, 90, 0.6);
+}
+.dploy-panel .dploy-msg {
+  margin-top: 0.45rem;
+  min-height: 1.1em;
+  font-size: 0.88em;
+  opacity: 0.85;
+}
+.dploy-panel.dploy-busy {
+  opacity: 0.7;
+}
diff --git a/integrations/ctfd_dploy/assets/dploy.js b/integrations/ctfd_dploy/assets/dploy.js
new file mode 100644
index 0000000..a7f025a
--- /dev/null
+++ b/integrations/ctfd_dploy/assets/dploy.js
@@ -0,0 +1,251 @@
+// Copyright the Dploy authors.
+// SPDX-License-Identifier: MIT
+//
+// Injected on every CTFd page. When a challenge whose connection-info is a Dploy
+// run URL (e.g. https://dploy.example.com/run/podinfo) is opened, this script
+// adds Start / Status / Extend / Stop controls to the challenge modal and wires
+// them to the plugin's same-origin proxy. No Dploy token ever lives in the page.
+(function () {
+  "use strict";
+
+  var PLUGIN = "/plugins/ctfd_dploy";
+  var pattern = null; // RegExp, loaded from the backend so both sides agree.
+
+  // ---- helpers -------------------------------------------------------------
+
+  function csrf() {
+    try {
+      if (window.CTFd && CTFd.config && CTFd.config.csrfNonce) return CTFd.config.csrfNonce;
+    } catch (e) {}
+    return window.csrfNonce || (window.init && window.init.csrfNonce) || "";
+  }
+
+  function api(method, url) {
+    return fetch(url, {
+      method: method,
+      credentials: "same-origin",
+      headers: { "Accept": "application/json", "CSRF-Token": csrf() },
+    }).then(function (r) {
+      return r.json().catch(function () { return {}; }).then(function (body) {
+        return { status: r.status, body: body };
+      });
+    });
+  }
+
+  // Run the trusted (auto-approved) OIDC popup so the backend can mint a Dploy
+  // token for this user, then resolve. Falls back to a full-page redirect when
+  // popups are blocked.
+  function ensureAuth(loginUrl) {
+    return new Promise(function (resolve, reject) {
+      var win = window.open(loginUrl, "dploy-auth", "width=480,height=640");
+      if (!win) {
+        window.location = loginUrl.replace("popup=1", "next=" + encodeURIComponent(location.pathname));
+        return; // navigating away
+      }
+      var done = false;
+      function onMsg(ev) {
+        if (ev.origin !== window.location.origin) return;
+        if (!ev.data || ev.data.type !== "dploy-auth") return;
+        done = true;
+        window.removeEventListener("message", onMsg);
+        ev.data.ok ? resolve() : reject(new Error("Dploy sign-in was cancelled"));
+      }
+      window.addEventListener("message", onMsg);
+      var poll = setInterval(function () {
+        if (win.closed) {
+          clearInterval(poll);
+          window.removeEventListener("message", onMsg);
+          if (!done) reject(new Error("Dploy sign-in window closed"));
+        }
+      }, 500);
+    });
+  }
+
+  // Call a proxy action, transparently handling the one-time auth bounce.
+  function action(cid, verb, method, retried) {
+    return api(method, PLUGIN + "/challenges/" + cid + "/" + verb).then(function (res) {
+      if (res.status === 401 && res.body && res.body.error === "auth_required" && !retried) {
+        return ensureAuth(res.body.login_url).then(function () {
+          return action(cid, verb, method, true);
+        });
+      }
+      if (!res.body || res.body.success !== true) {
+        var msg = (res.body && res.body.error) || ("HTTP " + res.status);
+        throw new Error(msg);
+      }
+      return res.body.data || {};
+    });
+  }
+
+  // ---- panel rendering -----------------------------------------------------
+
+  function fmtExpiry(iso) {
+    if (!iso) return "no expiry";
+    var d = new Date(iso);
+    if (isNaN(d)) return iso;
+    var mins = Math.round((d - new Date()) / 60000);
+    if (mins <= 0) return "expired";
+    if (mins < 60) return "expires in " + mins + " min";
+    return "expires in " + Math.round(mins / 60) + "h " + (mins % 60) + "m";
+  }
+
+  function renderState(panel, data) {
+    var status = (data && (data.status || data.Status)) || "";
+    var url = (data && (data.url || data.URL)) || "";
+    var exp = (data && (data.expiresAt || data.ExpiresAt)) || "";
+    var msg = (data && (data.connectionMessage || data.ConnectionMessage)) || "";
+    var running = !!status && status.toLowerCase() !== "pending" && status !== "Deleting";
+
+    var bits = [];
+    if (status) bits.push('<span class="dploy-badge">' + escapeHtml(status) + "</span>");
+    if (running) bits.push('<span class="dploy-exp">' + escapeHtml(fmtExpiry(exp)) + "</span>");
+    panel.querySelector(".dploy-state").innerHTML = bits.join(" ") || "Not running";
+
+    var link = panel.querySelector(".dploy-link");
+    if (url) {
+      link.innerHTML = '<a href="' + escapeAttr(url) + '" target="_blank" rel="noopener">' +
+        escapeHtml(url) + "</a>";
+    } else if (msg) {
+      link.textContent = msg;
+    } else {
+      link.textContent = "";
+    }
+
+    panel.querySelector('[data-act="start"]').disabled = running;
+    panel.querySelector('[data-act="extend"]').disabled = !running;
+    panel.querySelector('[data-act="stop"]').disabled = !running;
+  }
+
+  function setBusy(panel, busy, note) {
+    panel.classList.toggle("dploy-busy", !!busy);
+    if (note !== undefined) panel.querySelector(".dploy-msg").textContent = note || "";
+  }
+
+  function buildPanel(cid) {
+    var el = document.createElement("div");
+    el.className = "dploy-panel";
+    el.setAttribute("data-dploy-cid", String(cid));
+    el.innerHTML =
+      '<div class="dploy-head">Environment</div>' +
+      '<div class="dploy-state">…</div>' +
+      '<div class="dploy-link"></div>' +
+      '<div class="dploy-actions">' +
+      '  <button type="button" class="dploy-btn dploy-start" data-act="start">Start</button>' +
+      '  <button type="button" class="dploy-btn" data-act="status">Refresh</button>' +
+      '  <button type="button" class="dploy-btn" data-act="extend">Extend</button>' +
+      '  <button type="button" class="dploy-btn dploy-stop" data-act="stop">Stop</button>' +
+      "</div>" +
+      '<div class="dploy-msg"></div>';
+
+    var verbs = {
+      start: { method: "POST", note: "Starting environment…" },
+      status: { method: "GET", note: "" },
+      extend: { method: "POST", note: "Extending…" },
+      stop: { method: "POST", note: "Stopping…" },
+    };
+
+    el.querySelectorAll("[data-act]").forEach(function (btn) {
+      btn.addEventListener("click", function () {
+        var act = btn.getAttribute("data-act");
+        var spec = verbs[act];
+        setBusy(el, true, spec.note);
+        action(cid, act, spec.method)
+          .then(function (data) {
+            if (act === "stop") {
+              renderState(el, {});
+              setBusy(el, false, "Environment stopped.");
+            } else {
+              renderState(el, data);
+              setBusy(el, false, act === "extend" ? "Extended." : "");
+            }
+          })
+          .catch(function (err) {
+            setBusy(el, false, "Error: " + err.message);
+          });
+      });
+    });
+    return el;
+  }
+
+  function refresh(panel, cid) {
+    setBusy(panel, true, "");
+    action(cid, "status", "GET")
+      .then(function (data) { renderState(panel, data); setBusy(panel, false); })
+      .catch(function (err) {
+        // 404 / not-running is normal — show the idle state, surface real errors.
+        renderState(panel, {});
+        setBusy(panel, false, /not running|not found|404|unknown/i.test(err.message) ? "" : err.message);
+      });
+  }
+
+  // ---- modal detection -----------------------------------------------------
+
+  // The currently-open challenge object CTFd stashes while rendering the modal.
+  function currentChallenge() {
+    try { return window.CTFd._internal.challenge.data || null; } catch (e) { return null; }
+  }
+
+  function findModalBody() {
+    // The visible challenge modal varies by theme; try the common anchors.
+    var sel = [
+      ".modal.show .modal-body",
+      "#challenge-window .modal-body",
+      "#challenge-window",
+      ".challenge-desc",
+    ];
+    for (var i = 0; i < sel.length; i++) {
+      var nodes = document.querySelectorAll(sel[i]);
+      for (var j = 0; j < nodes.length; j++) {
+        if (nodes[j].offsetParent !== null) return nodes[j];
+      }
+    }
+    return null;
+  }
+
+  function maybeDecorate() {
+    if (!pattern) return;
+    var chal = currentChallenge();
+    if (!chal || !chal.id) return;
+    var ci = chal.connection_info || chal.connectionInfo || "";
+    if (!ci || !pattern.test(ci)) return;
+
+    var body = findModalBody();
+    if (!body) return;
+
+    var existing = body.querySelector(".dploy-panel");
+    if (existing) {
+      if (existing.getAttribute("data-dploy-cid") === String(chal.id)) return; // already done
+      existing.remove(); // a different challenge reused the modal
+    }
+    var panel = buildPanel(chal.id);
+    body.appendChild(panel);
+    refresh(panel, chal.id);
+  }
+
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c];
+    });
+  }
+  function escapeAttr(s) { return escapeHtml(s); }
+
+  // ---- bootstrap -----------------------------------------------------------
+
+  function start() {
+    fetch(PLUGIN + "/config", { credentials: "same-origin" })
+      .then(function (r) { return r.json(); })
+      .then(function (cfg) {
+        try { pattern = new RegExp(cfg.pattern); } catch (e) { pattern = null; }
+        var obs = new MutationObserver(function () { maybeDecorate(); });
+        obs.observe(document.body, { childList: true, subtree: true });
+        maybeDecorate();
+      })
+      .catch(function () { /* config unavailable; stay inert */ });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", start);
+  } else {
+    start();
+  }
+})();
diff --git a/integrations/ctfd_dploy/config.json b/integrations/ctfd_dploy/config.json
new file mode 100644
index 0000000..3a6cd83
--- /dev/null
+++ b/integrations/ctfd_dploy/config.json
@@ -0,0 +1,4 @@
+{
+  "name": "Dploy",
+  "version": "0.1.0"
+}
diff --git a/integrations/ctfd_dploy/dploy_client.py b/integrations/ctfd_dploy/dploy_client.py
new file mode 100644
index 0000000..7bc4b2a
--- /dev/null
+++ b/integrations/ctfd_dploy/dploy_client.py
@@ -0,0 +1,68 @@
+# Copyright the Dploy authors.
+# SPDX-License-Identifier: MIT
+"""
+Tiny client for the Dploy REST API.
+
+Maps the four challenge actions onto Dploy's `/api/run/{template}` endpoints:
+
+    start   -> GET    /api/run/{template}           (create-or-get)
+    status  -> GET    /api/run/{template}/status
+    extend  -> POST   /api/run/{template}/extend
+    stop    -> DELETE /api/run/{template}
+
+Every call carries the caller's CTFd-issued id_token as a Bearer token.
+"""
+
+import requests
+
+TIMEOUT = 20
+
+
+class DployError(Exception):
+    """A non-2xx response from Dploy. ``status`` is the HTTP code, ``payload``
+    the decoded JSON body (or raw text)."""
+
+    def __init__(self, status, payload):
+        self.status = status
+        self.payload = payload
+        msg = payload.get("error") if isinstance(payload, dict) else str(payload)
+        super().__init__(msg or "dploy request failed")
+
+
+class DployClient:
+    def __init__(self, base_url, token):
+        self.base = base_url.rstrip("/")
+        self.token = token
+
+    # -- low level ----------------------------------------------------------
+
+    def _request(self, method, path):
+        url = self.base + path
+        headers = {
+            "Authorization": "Bearer " + self.token,
+            "Accept": "application/json",
+        }
+        resp = requests.request(method, url, headers=headers, timeout=TIMEOUT)
+        if resp.status_code == 204:
+            return {}
+        try:
+            body = resp.json()
+        except ValueError:
+            body = resp.text
+        if not (200 <= resp.status_code < 300):
+            raise DployError(resp.status_code, body)
+        return body
+
+    # -- actions ------------------------------------------------------------
+
+    def start(self, template):
+        return self._request("GET", "/api/run/%s" % template)
+
+    def status(self, template):
+        return self._request("GET", "/api/run/%s/status" % template)
+
+    def extend(self, template):
+        return self._request("POST", "/api/run/%s/extend" % template)
+
+    def stop(self, template):
+        return self._request("DELETE", "/api/run/%s" % template)
diff --git a/integrations/ctfd_dploy/oidc.py b/integrations/ctfd_dploy/oidc.py
new file mode 100644
index 0000000..ede5e7b
--- /dev/null
+++ b/integrations/ctfd_dploy/oidc.py
@@ -0,0 +1,224 @@
+# Copyright the Dploy authors.
+# SPDX-License-Identifier: MIT
+"""
+Token broker for the Dploy CTFd plugin.
+
+CTFd is itself the OIDC Provider of Dploy (via the companion
+`ctfd-oidc-provider` plugin), so the only thing the proxy needs in order to call
+the Dploy API on a user's behalf is a CTFd-issued ``id_token`` for that user.
+
+We obtain it with a *standard* Authorization-Code + PKCE flow against CTFd's own
+``/oauth/authorize`` and ``/oauth/token`` endpoints. Because the OAuth client is
+registered as **trusted**, a logged-in user hitting ``/oauth/authorize`` is
+auto-approved and bounced straight back with a code — no consent screen — so the
+round-trip is effectively invisible. The resulting ``id_token`` is cached in the
+*server-side* Flask session and never exposed to the browser.
+
+The audience (``aud``) of the token equals the configured client id, so it must
+match Dploy's ``JWT_AUDIENCE`` (default ``dploy``); the username comes from the
+``name`` claim, so the ``profile`` scope must be requested (Dploy's default
+``JWT_USERNAME_CLAIM=name``). Get those two right and, as intended, no auth
+problem can appear.
+"""
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import time
+from urllib.parse import urlencode
+
+import requests
+from flask import current_app, request, session, url_for
+
+# --- Configuration ----------------------------------------------------------
+#
+# Every value is read at call time so it can come from an environment variable
+# *or* the CTFd app config (``app.config[...]``), with env taking precedence.
+
+_DISCOVERY_CACHE = {}
+_DISCOVERY_TTL = 600  # seconds
+
+SESSION_KEY = "dploy_oidc"          # holds {"id_token", "exp"}
+SESSION_FLOW = "dploy_oidc_flow"    # holds {"state", "verifier", "next", "popup"}
+
+
+def cfg(name, default=None):
+    """Look up a setting from the environment first, then CTFd app config."""
+    val = os.environ.get(name)
+    if val is not None and val != "":
+        return val
+    try:
+        val = current_app.config.get(name)
+    except Exception:
+        val = None
+    return val if val not in (None, "") else default
+
+
+def issuer():
+    """
+    OIDC issuer to talk to. Defaults to the CTFd provider's own issuer
+    (``OIDC_PROVIDER_ISSUER``), falling back to this request's host so a
+    single-host dev setup works with zero config.
+    """
+    iss = cfg("DPLOY_OIDC_ISSUER") or cfg("OIDC_PROVIDER_ISSUER")
+    if iss:
+        return iss.rstrip("/")
+    return request.url_root.rstrip("/")
+
+
+def client_id():
+    # Must match Dploy's JWT_AUDIENCE (default "dploy") so the token's `aud`
+    # passes Dploy's audience check.
+    return cfg("DPLOY_OIDC_CLIENT_ID", "dploy")
+
+
+def client_secret():
+    return cfg("DPLOY_OIDC_CLIENT_SECRET", "")
+
+
+def scopes():
+    # `profile` is required so the token carries the `name` claim that Dploy
+    # uses as the owner key (JWT_USERNAME_CLAIM=name).
+    return cfg("DPLOY_OIDC_SCOPES", "openid profile email")
+
+
+def redirect_uri():
+    explicit = cfg("DPLOY_OIDC_REDIRECT_URI")
+    if explicit:
+        return explicit
+    # Derived from the running CTFd host; must be registered as a redirect URI
+    # on the OAuth client.
+    return url_for("dploy.auth_callback", _external=True)
+
+
+# --- Discovery --------------------------------------------------------------
+
+def discovery():
+    """Fetch and cache the issuer's OpenID discovery document."""
+    iss = issuer()
+    cached = _DISCOVERY_CACHE.get(iss)
+    now = time.time()
+    if cached and cached["fetched"] + _DISCOVERY_TTL > now:
+        return cached["doc"]
+    url = iss + "/.well-known/openid-configuration"
+    resp = requests.get(url, timeout=10)
+    resp.raise_for_status()
+    doc = resp.json()
+    _DISCOVERY_CACHE[iss] = {"doc": doc, "fetched": now}
+    return doc
+
+
+# --- PKCE helpers -----------------------------------------------------------
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _new_pkce():
+    verifier = _b64url(secrets.token_bytes(40))
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+# --- Flow -------------------------------------------------------------------
+
+def begin_login(next_url="/challenges", popup=False):
+    """
+    Stash flow state in the session and return the provider authorize URL the
+    browser should be sent to.
+    """
+    verifier, challenge = _new_pkce()
+    state = secrets.token_urlsafe(24)
+    session[SESSION_FLOW] = {
+        "state": state,
+        "verifier": verifier,
+        "next": next_url,
+        "popup": bool(popup),
+    }
+    params = {
+        "response_type": "code",
+        "client_id": client_id(),
+        "redirect_uri": redirect_uri(),
+        "scope": scopes(),
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    return discovery()["authorization_endpoint"] + "?" + urlencode(params)
+
+
+def complete_login(req):
+    """
+    Handle the provider callback: validate state, exchange the code for tokens,
+    and cache the ``id_token`` in the session. Returns the stored flow dict
+    (so the caller knows where to redirect / whether it was a popup).
+    """
+    flow = session.pop(SESSION_FLOW, None)
+    if not flow:
+        raise ValueError("no in-progress Dploy login (missing session state)")
+
+    if req.args.get("error"):
+        raise ValueError(
+            "identity provider rejected the login: %s" % req.args.get("error")
+        )
+
+    if not secrets.compare_digest(req.args.get("state", ""), flow["state"]):
+        raise ValueError("state mismatch")
+
+    code = req.args.get("code")
+    if not code:
+        raise ValueError("missing authorization code")
+
+    token_endpoint = discovery()["token_endpoint"]
+    data = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": redirect_uri(),
+        "client_id": client_id(),
+        "code_verifier": flow["verifier"],
+    }
+    auth = None
+    secret = client_secret()
+    if secret:
+        # Confidential client → client_secret_basic.
+        auth = (client_id(), secret)
+    resp = requests.post(token_endpoint, data=data, auth=auth, timeout=15)
+    if resp.status_code != 200:
+        raise ValueError("token exchange failed: %s %s" % (resp.status_code, resp.text[:200]))
+    payload = resp.json()
+    id_token = payload.get("id_token")
+    if not id_token:
+        raise ValueError("token response had no id_token")
+
+    session[SESSION_KEY] = {"id_token": id_token, "exp": _jwt_exp(id_token)}
+    return flow
+
+
+def current_token():
+    """Return a still-valid cached ``id_token`` for this session, or ``None``."""
+    data = session.get(SESSION_KEY)
+    if not data:
+        return None
+    # 30 s skew so we don't hand Dploy a token that expires mid-request.
+    if data.get("exp", 0) <= time.time() + 30:
+        session.pop(SESSION_KEY, None)
+        return None
+    return data["id_token"]
+
+
+def clear_token():
+    session.pop(SESSION_KEY, None)
+
+
+def _jwt_exp(token):
+    """Read the ``exp`` claim from a JWT without verifying it (we trust our own
+    session storage; verification is Dploy's job)."""
+    try:
+        payload = token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(payload))
+        return int(claims.get("exp", 0))
+    except Exception:
+        return 0
diff --git a/integrations/ctfd_dploy/requirements.txt b/integrations/ctfd_dploy/requirements.txt
new file mode 100644
index 0000000..567b66a
--- /dev/null
+++ b/integrations/ctfd_dploy/requirements.txt
@@ -0,0 +1,2 @@
+# The plugin only needs an HTTP client; CTFd already ships Flask/SQLAlchemy.
+requests>=2.28
diff --git a/integrations/testing/Dockerfile.ctfd b/integrations/testing/Dockerfile.ctfd
new file mode 100644
index 0000000..3071490
--- /dev/null
+++ b/integrations/testing/Dockerfile.ctfd
@@ -0,0 +1,32 @@
+# CTFd image carrying both the OIDC provider and the Dploy plugin.
+#
+# Build context is the repo root (see docker-compose.yml) so this plugin's
+# source is available; the companion oidc_provider plugin is cloned at a pinned
+# ref. ctfd_dploy itself is bind-mounted by compose for live editing.
+ARG CTFD_VERSION=3.7.7
+FROM ctfd/ctfd:${CTFD_VERSION}
+
+USER root
+
+# git is needed to fetch the companion plugin; build deps for the JWT libs are
+# already present in the CTFd image.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git \
+ && rm -rf /var/lib/apt/lists/*
+
+# Plugin runtime deps: Authlib + PyYAML (oidc_provider), requests (ctfd_dploy;
+# usually already present, pinned here for safety).
+RUN pip install --no-cache-dir Authlib PyYAML "requests>=2.28"
+
+# Companion OIDC provider plugin. The repo layout puts the plugin either at the
+# repo root or under an oidc_provider/ subdir; handle both.
+ARG OIDC_PROVIDER_REF=main
+RUN git clone --depth 1 --branch ${OIDC_PROVIDER_REF} \
+      https://github.com/AYDEV-FR/ctfd-oidc-provider.git /tmp/oidcp \
+ && if [ -f /tmp/oidcp/__init__.py ]; then SRC=/tmp/oidcp; else SRC=/tmp/oidcp/oidc_provider; fi \
+ && cp -r "$SRC" /opt/CTFd/CTFd/plugins/oidc_provider \
+ && rm -rf /tmp/oidcp/.git \
+ && pip install --no-cache-dir -r /opt/CTFd/CTFd/plugins/oidc_provider/requirements.txt || true
+
+# Drop back to the unprivileged CTFd user.
+USER 1001
diff --git a/integrations/testing/README.md b/integrations/testing/README.md
new file mode 100644
index 0000000..888ef76
--- /dev/null
+++ b/integrations/testing/README.md
@@ -0,0 +1,92 @@
+# Test stack for the CTFd → Dploy plugin
+
+A self-contained Docker Compose stack to exercise the plugin end-to-end without
+a Kubernetes cluster.
+
+```
+┌────────────────────── docker network ──────────────────────┐
+│                                                             │
+│  Browser ──▶ CTFd (:8000)                                   │
+│              ├─ oidc_provider plugin  (CTFd is the IdP)      │
+│              └─ ctfd_dploy plugin     (proxy + token broker) │
+│                      │  Bearer id_token                      │
+│                      ▼                                       │
+│              dploy-mock (:8080) ── validates token vs        │
+│                                    CTFd's JWKS, just like     │
+│                                    real Dploy                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The **mock Dploy** validates the CTFd-issued token exactly as real Dploy does
+(RS256 vs CTFd's `/oauth/jwks`, `iss`/`aud` checks, owner from the `name`
+claim), so this proves the "no auth problems" wiring. It keeps environment state
+in memory — it does not provision anything real.
+
+## Run
+
+```bash
+cd integrations/testing
+docker compose up --build
+```
+
+Then:
+
+1. Open <http://localhost:8000> and complete CTFd's first-run setup (create the
+   admin account). The `dploy` OAuth client is already provisioned via
+   `oidc_apps.yaml`.
+2. **Admin → Challenges → + (Create)**: make any standard challenge and set its
+   **Connection Info** to:
+   ```
+   http://dploy-mock:8080/run/demo
+   ```
+   Save. (`demo` is the template name; the mock accepts any name.)
+3. Visit **Challenges** as a logged-in user and open that challenge. A panel
+   appears:
+   ```
+   Environment
+   Not running
+   [ Start ] [ Refresh ] [ Extend ] [ Stop ]
+   ```
+4. Click **Start**. The first action opens a brief CTFd OAuth popup that
+   auto-approves (trusted client) and closes; the panel then shows `Healthy`,
+   an expiry, and the environment URL. **Extend** pushes the expiry out;
+   **Stop** tears it down.
+
+> The environment URL (`http://<owner>-xxxx.dploy.local`) is a placeholder from
+> the mock and isn't browsable — the panel behavior is what's under test.
+
+## What this validates
+
+- Detection of a Dploy challenge purely from its Connection Info URL.
+- The server-side token broker: trusted auth-code+PKCE bounce → cached
+  `id_token` → `Bearer` forwarded to Dploy (token never reaches the browser).
+- `aud=dploy` / `iss` / `name`-claim alignment between CTFd and Dploy.
+- Start / Status / Extend / Stop mapped onto `/api/run/{template}`.
+
+## Configuration knobs
+
+The compose file sets everything; notable choices:
+
+- `WORKERS=4` on CTFd — the plugin makes server-side HTTP calls to CTFd's *own*
+  OIDC endpoints (discovery, token exchange). With a single worker those
+  self-calls would deadlock; ≥2 workers avoids it.
+- `AUTHLIB_INSECURE_TRANSPORT=1` — allows the OAuth flow over plain HTTP for
+  local testing only. Never set this in production.
+- `OIDC_PROVIDER_ISSUER=http://localhost:8000` — both the browser and CTFd's own
+  in-container loopback reach CTFd at `localhost:8000`, so no split-horizon
+  config is needed here; the mock still demonstrates split-horizon by fetching
+  JWKS at `http://ctfd:8000` while expecting `iss=http://localhost:8000`.
+
+## Reset
+
+```bash
+docker compose down -v     # also drops the CTFd DB / uploads volumes
+```
+
+## Pointing at a real Dploy instead of the mock
+
+Set `DPLOY_API_URL` (and the challenge Connection Info host) to your real Dploy
+URL, and make sure Dploy's `JWT_ISSUER` / `JWT_AUDIENCE` / `JWT_USERNAME_CLAIM`
+match this stack (`http://localhost:8000` / `dploy` / `name`). Remove the
+`dploy-mock` service. Real provisioning still requires Dploy's operator + a
+cluster — see the top-level README and `make setup`.
diff --git a/integrations/testing/docker-compose.yml b/integrations/testing/docker-compose.yml
new file mode 100644
index 0000000..1713ac4
--- /dev/null
+++ b/integrations/testing/docker-compose.yml
@@ -0,0 +1,70 @@
+# End-to-end test stack for the CTFd → Dploy plugin.
+#
+#   docker compose up --build
+#   open http://localhost:8000   (first run: create the admin account)
+#
+# What you get:
+#   * CTFd at :8000 with BOTH plugins loaded (oidc_provider + ctfd_dploy)
+#   * The "dploy" OAuth client pre-provisioned (trusted, confidential)
+#   * A mock Dploy API at :8080 that validates the CTFd-issued token exactly
+#     like real Dploy (iss / aud / signature against CTFd's JWKS), so the whole
+#     auth + proxy + UI path is exercised without a Kubernetes cluster.
+#
+# Then: log in, create a challenge whose Connection Info is
+#   http://dploy-mock:8080/run/demo
+# and the Start / Refresh / Extend / Stop panel appears in its modal.
+services:
+  ctfd:
+    build:
+      context: ../..
+      dockerfile: integrations/testing/Dockerfile.ctfd
+    container_name: ctfd-dploy-test
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    environment:
+      - AUTHLIB_INSECURE_TRANSPORT=1            # local HTTP only
+      - DATABASE_URL=sqlite:////data/ctfd.db
+      - SECRET_KEY=local-dev-not-secret-change-me
+      # >=2 so the plugin's server-side OIDC self-calls (discovery + token
+      # exchange to CTFd's own endpoints) are served by another worker and
+      # don't deadlock the request that issued them.
+      - WORKERS=4
+      # --- OIDC provider plugin ---
+      - OIDC_PROVIDER_ISSUER=http://localhost:8000
+      - OIDC_PROVIDER_JWK_FILE=/opt/CTFd/CTFd/uploads/oidc_jwks.json
+      - OIDC_PROVIDER_APPS_FILE=/etc/ctfd/oidc_apps.yaml
+      # --- ctfd_dploy plugin ---
+      - DPLOY_OIDC_ISSUER=http://localhost:8000
+      - DPLOY_OIDC_CLIENT_ID=dploy
+      - DPLOY_OIDC_CLIENT_SECRET=dploy-secret
+      - DPLOY_OIDC_REDIRECT_URI=http://localhost:8000/plugins/ctfd_dploy/auth/callback
+      - DPLOY_API_URL=http://dploy-mock:8080      # allowlist + base for the proxy
+    volumes:
+      # Live-mount this plugin so you can edit it and just restart CTFd.
+      - ../ctfd_dploy:/opt/CTFd/CTFd/plugins/ctfd_dploy:ro
+      - ./oidc_apps.yaml:/etc/ctfd/oidc_apps.yaml:ro
+      - ctfd_db:/data
+      - ctfd_uploads:/opt/CTFd/CTFd/uploads
+      - ctfd_logs:/opt/CTFd/CTFd/logs
+    depends_on:
+      - dploy-mock
+
+  dploy-mock:
+    build: ./dploy-mock
+    container_name: dploy-mock
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+    environment:
+      # Mirror real Dploy's JWT validation. JWKS is fetched in-network; the
+      # expected issuer is the public one the browser used (split-horizon).
+      - DPLOY_JWKS_URL=http://ctfd:8000/oauth/jwks
+      - DPLOY_JWT_ISSUER=http://localhost:8000
+      - DPLOY_JWT_AUDIENCE=dploy
+      - DPLOY_JWT_USERNAME_CLAIM=name
+
+volumes:
+  ctfd_db:
+  ctfd_uploads:
+  ctfd_logs:
diff --git a/integrations/testing/dploy-mock/Dockerfile b/integrations/testing/dploy-mock/Dockerfile
new file mode 100644
index 0000000..892028a
--- /dev/null
+++ b/integrations/testing/dploy-mock/Dockerfile
@@ -0,0 +1,10 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY app.py .
+
+EXPOSE 8080
+# A couple of workers so concurrent panel polls don't queue behind each other.
+CMD ["gunicorn", "-b", "0.0.0.0:8080", "-w", "2", "app:app"]
diff --git a/integrations/testing/dploy-mock/app.py b/integrations/testing/dploy-mock/app.py
new file mode 100644
index 0000000..e11205b
--- /dev/null
+++ b/integrations/testing/dploy-mock/app.py
@@ -0,0 +1,147 @@
+# Copyright the Dploy authors.
+# SPDX-License-Identifier: MIT
+"""
+Mock Dploy API for testing the CTFd plugin end-to-end.
+
+It implements the four `/api/run/{template}` endpoints the plugin calls and,
+crucially, validates the Bearer token the same way real Dploy does:
+
+  * RS256 signature against the CTFd provider's JWKS
+  * issuer (`iss`) and audience (`aud`) checks
+  * owner key derived from the configured username claim (default `name`),
+    sanitized identically to Dploy (lowercase; `.`/`@` -> `-`; drop the rest)
+
+Environment state is in-memory, keyed by (owner, template) — enough to exercise
+start / status / extend / stop and the TTL/expiry the panel renders. It does NOT
+provision anything real; that needs a Kubernetes cluster (`make setup`).
+"""
+
+import os
+import re
+import time
+import uuid
+
+import jwt  # PyJWT
+from jwt import PyJWKClient
+from flask import Flask, jsonify, request
+
+app = Flask(__name__)
+
+JWKS_URL = os.environ["DPLOY_JWKS_URL"]
+ISSUER = os.environ.get("DPLOY_JWT_ISSUER") or None
+AUDIENCE = os.environ.get("DPLOY_JWT_AUDIENCE") or None
+USERNAME_CLAIM = os.environ.get("DPLOY_JWT_USERNAME_CLAIM", "name")
+DEFAULT_TTL = int(os.environ.get("DPLOY_TTL_SECONDS", "3600"))
+EXTEND_TTL = int(os.environ.get("DPLOY_EXTEND_SECONDS", "3600"))
+
+# Lazily-initialized JWKS client (CTFd may still be starting up).
+_jwks = PyJWKClient(JWKS_URL)
+
+# (owner, template) -> {"uuid", "expires"}
+_instances = {}
+
+
+def sanitize(name):
+    """Match Dploy's SanitizeUsername: lowercase, '.'/'@' -> '-', keep [a-z0-9-]."""
+    name = (name or "").lower().replace(".", "-").replace("@", "-")
+    return re.sub(r"[^a-z0-9-]", "", name)
+
+
+def authed_owner():
+    """Return (owner, None) on success or (None, (json, status)) on failure."""
+    header = request.headers.get("Authorization", "")
+    if not header.startswith("Bearer "):
+        return None, (jsonify(error="Missing Authorization header"), 401)
+    token = header[len("Bearer "):]
+    try:
+        signing_key = _jwks.get_signing_key_from_jwt(token)
+        claims = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["RS256"],
+            audience=AUDIENCE,
+            issuer=ISSUER,
+            options={"verify_aud": AUDIENCE is not None},
+        )
+    except Exception as e:
+        return None, (jsonify(error="token validation failed: %s" % e), 401)
+    owner = sanitize(claims.get(USERNAME_CLAIM))
+    if not owner:
+        return None, (jsonify(error="missing or invalid %s claim" % USERNAME_CLAIM), 403)
+    return owner, None
+
+
+def _iso(ts):
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts))
+
+
+def _response(owner, template, inst):
+    short = inst["uuid"].split("-")[0]
+    return {
+        "uuid": inst["uuid"],
+        "status": "Healthy",
+        "url": "http://%s-%s.dploy.local" % (owner, short),
+        "expiresAt": _iso(inst["expires"]),
+        "owner": owner,
+        "shared": False,
+        "connectionType": "url",
+        "connectionMessage": "",
+    }
+
+
+@app.get("/health")
+def health():
+    return jsonify(status="ok")
+
+
+@app.get("/api/run/<template>")
+def start(template):
+    owner, err = authed_owner()
+    if err:
+        return err
+    key = (owner, template)
+    inst = _instances.get(key)
+    if inst is None:
+        inst = {"uuid": str(uuid.uuid4()), "expires": time.time() + DEFAULT_TTL}
+        _instances[key] = inst
+        app.logger.info("created %s for %s", template, owner)
+    return jsonify(_response(owner, template, inst))
+
+
+@app.get("/api/run/<template>/status")
+def status(template):
+    owner, err = authed_owner()
+    if err:
+        return err
+    inst = _instances.get((owner, template))
+    if inst is None:
+        return jsonify(error='environment "%s" not found' % template), 404
+    return jsonify(_response(owner, template, inst))
+
+
+@app.post("/api/run/<template>/extend")
+def extend(template):
+    owner, err = authed_owner()
+    if err:
+        return err
+    key = (owner, template)
+    inst = _instances.get(key)
+    if inst is None:
+        return jsonify(error='environment "%s" not found' % template), 404
+    inst["expires"] = max(inst["expires"], time.time()) + EXTEND_TTL
+    return jsonify(expiresAt=_iso(inst["expires"]))
+
+
+@app.delete("/api/run/<template>")
+def stop(template):
+    owner, err = authed_owner()
+    if err:
+        return err
+    if _instances.pop((owner, template), None) is None:
+        return jsonify(error='environment "%s" not found' % template), 404
+    app.logger.info("deleted %s for %s", template, owner)
+    return ("", 204)
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=8080)
diff --git a/integrations/testing/dploy-mock/requirements.txt b/integrations/testing/dploy-mock/requirements.txt
new file mode 100644
index 0000000..5af30f3
--- /dev/null
+++ b/integrations/testing/dploy-mock/requirements.txt
@@ -0,0 +1,4 @@
+Flask>=3.0
+PyJWT[crypto]>=2.8
+requests>=2.28
+gunicorn>=21.2
diff --git a/integrations/testing/oidc_apps.yaml b/integrations/testing/oidc_apps.yaml
new file mode 100644
index 0000000..dddf64a
--- /dev/null
+++ b/integrations/testing/oidc_apps.yaml
@@ -0,0 +1,20 @@
+# Declarative OAuth client provisioning for the OIDC provider plugin.
+# Upserted on CTFd startup (matched by client_id).
+#
+# The "dploy" client is shared by Dploy itself and the ctfd_dploy plugin: using
+# one client_id keeps the token `aud` aligned with Dploy's JWT_AUDIENCE=dploy,
+# which is why no auth problem appears. `trusted: true` makes the plugin's
+# auth-code bounce auto-approve (no consent screen).
+applications:
+  - name: Dploy
+    client_id: dploy
+    client_secret: dploy-secret
+    type: confidential
+    trusted: true
+    redirect_uris:
+      - http://localhost:8000/plugins/ctfd_dploy/auth/callback
+      # Add Dploy's own SPA callback here too in a real deployment, e.g.:
+      # - https://dploy.example.com/auth/callback
+    scopes: [openid, profile, email]
+    grant_types: [authorization_code, refresh_token]
+    token_endpoint_auth_method: client_secret_basic