oauth2-debugger 0.0.1__tar.gz

oauth2_debugger-0.0.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/

oauth2_debugger-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yike Xiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oauth2_debugger-0.0.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: oauth2-debugger
+Version: 0.0.1
+Summary: Local debugger for the OAuth2/OIDC Authorization Code flow (state, scopes, PKCE)
+Project-URL: Homepage, https://github.com/Shawyeok/oauth2-debugger
+Project-URL: Repository, https://github.com/Shawyeok/oauth2-debugger
+Author-email: Yike Xiao <kmter@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Provides-Extra: verify
+Requires-Dist: cryptography>=41; extra == 'verify'
+Description-Content-Type: text/markdown
+
+# oauth2-debugger
+
+A small, dependency-free local web app for manually driving an OAuth2/OIDC
+Authorization Code (+ PKCE) flow end-to-end against a real authorization server.
+Client ID, scope, issuer, and PKCE method are all configured on the page itself —
+no flags to memorize for a one-off test.
+
+A generic RFC 6749 / RFC 7636 client — point it at any OIDC-compliant
+authorization server via `--issuer` (or fill it in on the page itself).
+
+## Quick start
+
+```bash
+uvx oauth2-debugger
+```
+
+Or from a checkout:
+
+```bash
+cd oauth2-debugger
+uv run oauth2-debugger
+```
+
+Or without `uv`:
+
+```bash
+pip install -e .
+oauth2-debugger
+```
+
+Or straight from the source tree with plain stdlib Python, no install:
+
+```bash
+python3 -m oauth2_debugger
+```
+
+This opens `http://127.0.0.1:<port>/` in your browser (an OS-assigned ephemeral
+port by default — printed to the console either way). Fill in the client_id and
+scope, click **Start Authorization**, approve consent if prompted, and you land
+back on the same page with the full token response and decoded/verified claims.
+
+## What it does
+
+1. **Form page** (`GET /`): issuer, client_id, scope, PKCE method, endpoint
+   overrides, extra authorize-request params — all editable, pre-filled from
+   whatever you ran last (and from the `--client-id`/`--scope`/etc. CLI flags on
+   first load).
+2. **`POST /start`**: discovers the authorize/token/jwks endpoints from
+   `<issuer>/.well-known/openid-configuration` (unless you filled in the endpoint
+   overrides), generates a random `state` and a PKCE verifier/challenge pair,
+   remembers them server-side keyed by `state`, and 302s your browser to the real
+   authorization server.
+3. The redirect_uri is always `http://127.0.0.1:<this server's port>/callback` —
+   this relies on the authorization server implementing RFC 8252 §7.3 loopback
+   redirect matching (any port accepted as long as host + path match what's
+   registered; Spring Authorization Server does this). So the *registered* client
+   only ever needs `http://127.0.0.1/callback` on file, regardless of which port
+   this tool happens to bind on a given run.
+4. You approve consent (or it's skipped if already granted for that
+   client+account+scope set) and land back on **`GET /callback`**, which validates
+   the returned `state` against what was stored for it (rejects unknown/reused/
+   expired state — pending flows are kept for 15 minutes), extracts `code`, and
+   exchanges it at the token endpoint (with `code_verifier` if PKCE is enabled).
+5. **Results page**: full token response JSON, each of `access_token`/`id_token`
+   decoded and displayed with a copy button, and — if "verify JWT signatures" is
+   on — an inline PASS/FAIL badge from checking the RS256 signature against the
+   issuer's published JWKS. `refresh_token` gets its own copy button too.
+
+## CLI flags (seed the form / control the local server)
+
+```
+--host HOST                     default: 127.0.0.1
+--port N                        default: 0 (OS-assigned ephemeral, to avoid
+                                 colliding with whatever else is running on your
+                                 machine; pass a fixed port for a bookmarkable URL)
+--issuer URL                    default: https://auth.example.com
+--client-id ID                  default form value (still editable on the page)
+--scope "a b c"                 default form value (default: openid)
+--pkce-method S256|plain|none   default form value (default: S256)
+--no-verify-jwks                default the verify-signature toggle to off
+--no-browser                    don't auto-open the form page
+```
+
+## Registering a test client
+
+Point `--issuer` at your own authorization server and register a public
+(no client secret), loopback-redirect client against it:
+
+```
+redirect_uris:  http://127.0.0.1/callback   (any port accepted per RFC 8252,
+                                              if your server supports it)
+auth method:    none (public client, PKCE required)
+grant types:    authorization_code, refresh_token
+```
+
+Consult your authorization server's own docs for how to register a client —
+that part is intentionally out of scope for this generic debugging tool.

oauth2_debugger-0.0.1/README.md

@@ -0,0 +1,97 @@
+# oauth2-debugger
+
+A small, dependency-free local web app for manually driving an OAuth2/OIDC
+Authorization Code (+ PKCE) flow end-to-end against a real authorization server.
+Client ID, scope, issuer, and PKCE method are all configured on the page itself —
+no flags to memorize for a one-off test.
+
+A generic RFC 6749 / RFC 7636 client — point it at any OIDC-compliant
+authorization server via `--issuer` (or fill it in on the page itself).
+
+## Quick start
+
+```bash
+uvx oauth2-debugger
+```
+
+Or from a checkout:
+
+```bash
+cd oauth2-debugger
+uv run oauth2-debugger
+```
+
+Or without `uv`:
+
+```bash
+pip install -e .
+oauth2-debugger
+```
+
+Or straight from the source tree with plain stdlib Python, no install:
+
+```bash
+python3 -m oauth2_debugger
+```
+
+This opens `http://127.0.0.1:<port>/` in your browser (an OS-assigned ephemeral
+port by default — printed to the console either way). Fill in the client_id and
+scope, click **Start Authorization**, approve consent if prompted, and you land
+back on the same page with the full token response and decoded/verified claims.
+
+## What it does
+
+1. **Form page** (`GET /`): issuer, client_id, scope, PKCE method, endpoint
+   overrides, extra authorize-request params — all editable, pre-filled from
+   whatever you ran last (and from the `--client-id`/`--scope`/etc. CLI flags on
+   first load).
+2. **`POST /start`**: discovers the authorize/token/jwks endpoints from
+   `<issuer>/.well-known/openid-configuration` (unless you filled in the endpoint
+   overrides), generates a random `state` and a PKCE verifier/challenge pair,
+   remembers them server-side keyed by `state`, and 302s your browser to the real
+   authorization server.
+3. The redirect_uri is always `http://127.0.0.1:<this server's port>/callback` —
+   this relies on the authorization server implementing RFC 8252 §7.3 loopback
+   redirect matching (any port accepted as long as host + path match what's
+   registered; Spring Authorization Server does this). So the *registered* client
+   only ever needs `http://127.0.0.1/callback` on file, regardless of which port
+   this tool happens to bind on a given run.
+4. You approve consent (or it's skipped if already granted for that
+   client+account+scope set) and land back on **`GET /callback`**, which validates
+   the returned `state` against what was stored for it (rejects unknown/reused/
+   expired state — pending flows are kept for 15 minutes), extracts `code`, and
+   exchanges it at the token endpoint (with `code_verifier` if PKCE is enabled).
+5. **Results page**: full token response JSON, each of `access_token`/`id_token`
+   decoded and displayed with a copy button, and — if "verify JWT signatures" is
+   on — an inline PASS/FAIL badge from checking the RS256 signature against the
+   issuer's published JWKS. `refresh_token` gets its own copy button too.
+
+## CLI flags (seed the form / control the local server)
+
+```
+--host HOST                     default: 127.0.0.1
+--port N                        default: 0 (OS-assigned ephemeral, to avoid
+                                 colliding with whatever else is running on your
+                                 machine; pass a fixed port for a bookmarkable URL)
+--issuer URL                    default: https://auth.example.com
+--client-id ID                  default form value (still editable on the page)
+--scope "a b c"                 default form value (default: openid)
+--pkce-method S256|plain|none   default form value (default: S256)
+--no-verify-jwks                default the verify-signature toggle to off
+--no-browser                    don't auto-open the form page
+```
+
+## Registering a test client
+
+Point `--issuer` at your own authorization server and register a public
+(no client secret), loopback-redirect client against it:
+
+```
+redirect_uris:  http://127.0.0.1/callback   (any port accepted per RFC 8252,
+                                              if your server supports it)
+auth method:    none (public client, PKCE required)
+grant types:    authorization_code, refresh_token
+```
+
+Consult your authorization server's own docs for how to register a client —
+that part is intentionally out of scope for this generic debugging tool.

oauth2_debugger-0.0.1/oauth2_debugger/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

oauth2_debugger-0.0.1/oauth2_debugger/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oauth2_debugger-0.0.1/oauth2_debugger/cli.py

@@ -0,0 +1,73 @@
+"""Entry point: starts the local web app for driving OAuth2/OIDC Authorization Code
+(+ PKCE) flows. Client ID, scope, issuer, and PKCE method are all configured on the
+page itself (http://127.0.0.1:<port>/) rather than as required CLI flags -- the flags
+below only seed the form's defaults / control how the local server itself runs.
+"""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import webapp
+
+DEFAULT_ISSUER = "https://auth.example.com"
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="oauth2-debugger",
+        description=(
+            "Local web app for driving an OAuth2/OIDC Authorization Code (+ PKCE) flow against a "
+            "real authorization server. Configure client_id/scope/issuer on the page it opens."
+        ),
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind the local web app to (default: 127.0.0.1)")
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=0,
+        help="Port to bind the local web app to (default: 0 = OS-assigned ephemeral port, to avoid "
+        "colliding with whatever else is already running on your machine). Loopback redirect_uris "
+        "match on host+path regardless of port (RFC 8252), so any port works against a "
+        "spec-compliant authorization server. Pass a fixed port if you want a bookmarkable URL.",
+    )
+    parser.add_argument("--issuer", default=DEFAULT_ISSUER, help=f"Default issuer shown on the form (default: {DEFAULT_ISSUER})")
+    parser.add_argument("--client-id", default="", help="Default client_id shown on the form")
+    parser.add_argument("--scope", default="openid", help="Default scope shown on the form")
+    parser.add_argument(
+        "--pkce-method",
+        choices=["S256", "plain", "none"],
+        default="S256",
+        help="Default PKCE method shown on the form (default: S256)",
+    )
+    parser.add_argument(
+        "--no-verify-jwks",
+        action="store_true",
+        help="Default the 'verify JWT signatures' toggle to off (it's on by default)",
+    )
+    parser.add_argument("--no-browser", action="store_true", help="Don't auto-open the form page in a browser")
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_arg_parser().parse_args(argv)
+    defaults = {
+        "issuer": args.issuer,
+        "client_id": args.client_id,
+        "scope": args.scope,
+        "pkce_method": args.pkce_method,
+        "verify_jwks": "no" if args.no_verify_jwks else "yes",
+        "authorize_endpoint": "",
+        "token_endpoint": "",
+    }
+    try:
+        webapp.run(host=args.host, port=args.port, defaults=defaults, open_browser=not args.no_browser)
+    except OSError as exc:
+        print(f"error: could not bind {args.host}:{args.port}: {exc}", file=sys.stderr)
+        print("       try a different --port, or --port 0 for an OS-assigned one.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oauth2_debugger-0.0.1/oauth2_debugger/discovery.py

@@ -0,0 +1,17 @@
+"""Fetch OIDC / RFC 8414 OAuth2 discovery metadata."""
+
+import json
+import urllib.request
+
+
+def fetch_metadata(issuer: str) -> dict:
+    issuer = issuer.rstrip("/")
+    last_error = None
+    for suffix in ("/.well-known/openid-configuration", "/.well-known/oauth-authorization-server"):
+        url = issuer + suffix
+        try:
+            with urllib.request.urlopen(url, timeout=10) as resp:
+                return json.load(resp)
+        except Exception as exc:  # noqa: BLE001 - fall through and try the next discovery doc
+            last_error = exc
+    raise RuntimeError(f"could not fetch discovery metadata from {issuer}: {last_error}")

oauth2_debugger-0.0.1/oauth2_debugger/jwt_utils.py

@@ -0,0 +1,53 @@
+"""Decode (and optionally verify) JWTs without a heavy JOSE dependency."""
+
+import base64
+import json
+import urllib.request
+from typing import Tuple
+
+
+def _b64url_decode(segment: str) -> bytes:
+    padded = segment + "=" * (-len(segment) % 4)
+    return base64.urlsafe_b64decode(padded)
+
+
+def decode(token: str) -> Tuple[dict, dict]:
+    header_b64, payload_b64, _sig = token.split(".")
+    header = json.loads(_b64url_decode(header_b64))
+    payload = json.loads(_b64url_decode(payload_b64))
+    return header, payload
+
+
+def verify_signature(token: str, jwks_uri: str) -> bool:
+    """Best-effort RS256 verification against a JWKS endpoint. Requires `cryptography`."""
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.asymmetric import padding, rsa
+    except ImportError as exc:  # pragma: no cover - optional dependency
+        raise RuntimeError(
+            "signature verification requires the 'cryptography' package "
+            "(pip install 'oauth2-debugger[verify]')"
+        ) from exc
+
+    header_b64, payload_b64, sig_b64 = token.split(".")
+    header = json.loads(_b64url_decode(header_b64))
+    if header.get("alg") != "RS256":
+        raise RuntimeError(f"only RS256 verification is supported (token uses {header.get('alg')})")
+
+    with urllib.request.urlopen(jwks_uri, timeout=10) as resp:
+        jwks = json.load(resp)
+    key = next((k for k in jwks["keys"] if k["kid"] == header.get("kid")), None)
+    if key is None:
+        raise RuntimeError(f"no key with kid={header.get('kid')!r} found at {jwks_uri}")
+
+    n = int.from_bytes(_b64url_decode(key["n"]), "big")
+    e = int.from_bytes(_b64url_decode(key["e"]), "big")
+    public_key = rsa.RSAPublicNumbers(e, n).public_key()
+    signing_input = f"{header_b64}.{payload_b64}".encode("ascii")
+    signature = _b64url_decode(sig_b64)
+    try:
+        public_key.verify(signature, signing_input, padding.PKCS1v15(), hashes.SHA256())
+        return True
+    except InvalidSignature:
+        return False

oauth2_debugger-0.0.1/oauth2_debugger/pkce.py

@@ -0,0 +1,19 @@
+"""RFC 7636 PKCE code_verifier / code_challenge generation."""
+
+import base64
+import hashlib
+import secrets
+
+
+def generate_verifier(length: int = 64) -> str:
+    """A high-entropy verifier, base64url-encoded (43-128 chars per RFC 7636)."""
+    return base64.urlsafe_b64encode(secrets.token_bytes(length)).decode("ascii").rstrip("=")
+
+
+def challenge_for(verifier: str, method: str = "S256") -> str:
+    if method == "plain":
+        return verifier
+    if method == "S256":
+        digest = hashlib.sha256(verifier.encode("ascii")).digest()
+        return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+    raise ValueError(f"unsupported PKCE method: {method}")

oauth2_debugger-0.0.1/oauth2_debugger/webapp.py

@@ -0,0 +1,690 @@
+"""A tiny local web app for driving OAuth2/OIDC Authorization Code (+ PKCE) flows.
+
+Everything runs on a loopback HTTP server the debugger itself starts:
+
+  GET  /            configuration form (issuer, client_id, scope, PKCE method, ...)
+  POST /start        builds the authorize URL for the submitted config and 302s the
+                      browser to the real authorization server
+  GET  /callback      the redirect_uri target: receives code/state (or error), validates
+                      state, exchanges the code for tokens, renders the results page
+
+Only one flow needs to be "in flight" per browser tab, but multiple pending flows
+(different states) are tracked so opening several tabs / retrying doesn't collide.
+"""
+
+import html
+import json
+import secrets
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from . import jwt_utils, pkce
+from .discovery import fetch_metadata
+
+PENDING_TTL_SECONDS = 15 * 60
+
+PAGE_STYLE = """
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+       max-width: 860px; margin: 2rem auto; padding: 0 1.5rem; color: #1a1a1a; }
+h1 { font-size: 1.4rem; }
+h2 { font-size: 1.1rem; margin-top: 2rem; border-bottom: 1px solid #ddd; padding-bottom: .3rem; }
+label { display: block; margin-top: 1rem; font-weight: 600; font-size: .9rem; }
+input, select, textarea { width: 100%; box-sizing: border-box; padding: .5rem; margin-top: .25rem;
+       font-family: inherit; font-size: .95rem; border: 1px solid #ccc; border-radius: 4px; }
+textarea { font-family: ui-monospace, monospace; font-size: .85rem; min-height: 4rem; }
+.hint { color: #666; font-size: .8rem; margin-top: .2rem; }
+button { margin-top: 1.5rem; padding: .6rem 1.4rem; font-size: 1rem; border: none; border-radius: 4px;
+       background: #2b6cb0; color: white; cursor: pointer; }
+button:hover { background: #245a94; }
+button:disabled { opacity: .65; cursor: not-allowed; }
+button.secondary { background: #555; }
+.spinner { display: inline-block; width: .8em; height: .8em; margin-right: .5em; vertical-align: -1px;
+       border: 2px solid rgba(255,255,255,.45); border-top-color: #fff; border-radius: 50%;
+       animation: spin .6s linear infinite; }
+@keyframes spin { to { transform: rotate(360deg); } }
+pre { background: #f5f5f5; padding: 1rem; border-radius: 4px; overflow-x: auto; font-size: .82rem; }
+.token-box { position: relative; }
+.copy-btn { position: absolute; top: .5rem; right: .5rem; padding: .25rem .6rem; font-size: .75rem; }
+.badge { display: inline-block; padding: .1rem .5rem; border-radius: 3px; font-size: .75rem; font-weight: 600; }
+.badge.pass { background: #c6f6d5; color: #22543d; }
+.badge.fail { background: #fed7d7; color: #742a2a; }
+.badge.skip { background: #edf2f7; color: #4a5568; }
+.error { background: #fed7d7; color: #742a2a; padding: 1rem; border-radius: 4px; }
+.row { display: flex; gap: 1rem; }
+.row > * { flex: 1; }
+.input-with-btn { display: flex; gap: .4rem; margin-top: .25rem; }
+.input-with-btn input { margin-top: 0; }
+.regen-btn { margin-top: 0; padding: .5rem .7rem; font-size: 1rem; line-height: 1; flex: 0 0 auto;
+       background: #555; }
+.regen-btn:hover { background: #3d3d3d; }
+.scope-checkboxes { display: flex; flex-wrap: wrap; gap: .5rem; margin-top: .5rem; }
+.scope-item { display: inline-flex; align-items: center; gap: .35rem; margin: 0; padding: .35rem .6rem;
+       border: 1px solid #ccc; border-radius: 999px; font-weight: 400; font-size: .85rem; cursor: pointer; }
+.scope-item input { width: auto; margin: 0; padding: 0; }
+"""
+
+FORM_PAGE = """<!doctype html>
+<html><head><meta charset="utf-8"><title>oauth2-debugger</title><style>{style}</style></head>
+<body>
+<h1>OAuth2 / OIDC Authorization Code Debugger</h1>
+<p class="hint">Configure a client and scopes, start the flow, approve consent in the browser
+tab that opens, and land back here with the decoded tokens.</p>
+<form method="POST" action="/start" id="start-form">
+  <label>Authorization Server
+    <input name="issuer" id="issuer" value="{issuer}">
+  </label>
+  <p class="hint">Its &lt;issuer&gt;/.well-known/openid-configuration is fetched (through this
+    tool's own server, to sidestep CORS) to fill in the authorize/token endpoints below.</p>
+
+  <div class="row">
+    <label>Authorization endpoint (override)
+      <input name="authorize_endpoint" id="authorize_endpoint" value="{authorize_endpoint}"
+             placeholder="{discovered_authorize_endpoint}">
+    </label>
+    <label>Token endpoint (override)
+      <input name="token_endpoint" id="token_endpoint" value="{token_endpoint}"
+             placeholder="{discovered_token_endpoint}">
+    </label>
+  </div>
+  <p class="hint" id="discover-status"></p>
+
+  <label>Client ID
+    <input name="client_id" value="{client_id}" required>
+  </label>
+
+  <label>Scope
+    <div class="scope-checkboxes" id="scope-checkboxes">{scope_checkboxes}</div>
+    <input name="scope" id="scope" value="{scope}" placeholder="space-delimited scopes">
+  </label>
+  <p class="hint">Checkboxes above reflect this issuer's discovered <code>scopes_supported</code>
+    and stay in sync with the field below. The field is still plain text, though — type (or leave)
+    anything there, including a scope the server never advertised, to see how it handles that.</p>
+
+  <div class="row">
+    <label>PKCE method
+      <select name="pkce_method">
+        <option value="S256" {sel_s256}>S256</option>
+        <option value="plain" {sel_plain}>plain</option>
+        <option value="none" {sel_none}>none (disable PKCE)</option>
+      </select>
+    </label>
+    <label>Verify JWT signatures against JWKS
+      <select name="verify_jwks">
+        <option value="yes" {verify_yes}>yes</option>
+        <option value="no" {verify_no}>no</option>
+      </select>
+    </label>
+  </div>
+
+  <div class="row">
+    <label>state
+      <div class="input-with-btn">
+        <input name="state" id="state" value="{state}">
+        <button type="button" class="regen-btn" data-target="state" title="Regenerate">&#8635;</button>
+      </div>
+    </label>
+    <label>nonce
+      <div class="input-with-btn">
+        <input name="nonce" id="nonce" value="{nonce}">
+        <button type="button" class="regen-btn" data-target="nonce" title="Regenerate">&#8635;</button>
+      </div>
+    </label>
+  </div>
+  <p class="hint">Both are random by default (regenerate freely). <code>state</code> also keys this
+    tool's own bookkeeping for the pending flow, so it's never actually sent empty even if you clear
+    it here. <code>nonce</code> has no such requirement — clear it to test an authorize request with
+    no nonce at all; if it's set and the response includes an <code>id_token</code>, the results page
+    checks the nonce came back unchanged.</p>
+
+  <label>Extra authorize-request params (one KEY=VALUE per line, optional)
+    <textarea name="extra_params" placeholder="scene=oidc-authorize"></textarea>
+  </label>
+
+  <button type="submit" id="start-btn">Start Authorization</button>
+</form>
+<script>
+document.getElementById('start-form').addEventListener('submit', function() {{
+  var btn = document.getElementById('start-btn');
+  btn.disabled = true;
+  btn.innerHTML = '<span class="spinner"></span>Starting...';
+}});
+var knownScopes = {known_scopes_json};
+
+function currentScopeWords() {{
+  return document.getElementById('scope').value.split(/\\s+/).filter(Boolean);
+}}
+
+function renderScopeCheckboxes() {{
+  var container = document.getElementById('scope-checkboxes');
+  if (!knownScopes.length) {{
+    container.innerHTML = '';
+    return;
+  }}
+  var checkedWords = currentScopeWords();
+  container.innerHTML = knownScopes.map(function(s) {{
+    var checked = checkedWords.indexOf(s) !== -1 ? 'checked' : '';
+    var safe = s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+    return '<label class="scope-item"><input type="checkbox" class="scope-checkbox" value="' + safe
+      + '" ' + checked + '>' + safe + '</label>';
+  }}).join('');
+  Array.prototype.forEach.call(container.querySelectorAll('.scope-checkbox'), function(cb) {{
+    cb.addEventListener('change', syncScopeFromCheckboxes);
+  }});
+}}
+
+function syncScopeFromCheckboxes() {{
+  var words = currentScopeWords();
+  var extra = words.filter(function(w) {{ return knownScopes.indexOf(w) === -1; }});
+  var checked = Array.prototype.map.call(
+    document.querySelectorAll('.scope-checkbox:checked'), function(cb) {{ return cb.value; }});
+  document.getElementById('scope').value = checked.concat(extra).join(' ');
+}}
+
+function syncCheckboxesFromScopeField() {{
+  var words = currentScopeWords();
+  Array.prototype.forEach.call(document.querySelectorAll('.scope-checkbox'), function(cb) {{
+    cb.checked = words.indexOf(cb.value) !== -1;
+  }});
+}}
+
+document.getElementById('scope').addEventListener('input', syncCheckboxesFromScopeField);
+
+function randomUrlSafeToken(byteLen) {{
+  var bytes = new Uint8Array(byteLen);
+  crypto.getRandomValues(bytes);
+  var binary = '';
+  bytes.forEach(function(b) {{ binary += String.fromCharCode(b); }});
+  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');
+}}
+Array.prototype.forEach.call(document.querySelectorAll('.regen-btn'), function(btn) {{
+  btn.addEventListener('click', function() {{
+    document.getElementById(btn.dataset.target).value = randomUrlSafeToken(18);
+  }});
+}});
+
+function refreshEndpointPlaceholders() {{
+  var issuer = document.getElementById('issuer').value.trim();
+  var status = document.getElementById('discover-status');
+  var azInput = document.getElementById('authorize_endpoint');
+  var tkInput = document.getElementById('token_endpoint');
+  if (!issuer) {{ status.textContent = ''; return; }}
+  status.textContent = 'Discovering endpoints from ' + issuer + ' ...';
+  fetch('/discover?issuer=' + encodeURIComponent(issuer))
+    .then(function(r) {{ return r.json(); }})
+    .then(function(data) {{
+      if (data.error) {{
+        status.textContent = 'Discovery failed: ' + data.error;
+        return;
+      }}
+      azInput.placeholder = data.authorization_endpoint || '';
+      tkInput.placeholder = data.token_endpoint || '';
+      knownScopes = data.scopes_supported || [];
+      renderScopeCheckboxes();
+      status.textContent = 'Discovered from ' + issuer + '/.well-known/openid-configuration';
+    }})
+    .catch(function(err) {{ status.textContent = 'Discovery failed: ' + err; }});
+}}
+document.addEventListener('DOMContentLoaded', function() {{
+  renderScopeCheckboxes();  // wire up listeners on the server-rendered checkboxes immediately
+  refreshEndpointPlaceholders();  // then re-fetch to catch up with any change since page render
+}});
+document.getElementById('issuer').addEventListener('change', refreshEndpointPlaceholders);
+</script>
+</body></html>
+"""
+
+ERROR_PAGE = """<!doctype html>
+<html><head><meta charset="utf-8"><title>oauth2-debugger - error</title><style>{style}</style></head>
+<body>
+<h1>oauth2-debugger</h1>
+<div class="error"><strong>{heading}</strong><p>{message}</p></div>
+<p><a href="/">&larr; back to the form</a></p>
+</body></html>
+"""
+
+RESULTS_PAGE = """<!doctype html>
+<html><head><meta charset="utf-8"><title>oauth2-debugger - result</title><style>{style}</style>
+<script>
+function copyIt(id) {{
+  const el = document.getElementById(id);
+  navigator.clipboard.writeText(el.textContent).then(() => {{
+    const btn = document.getElementById(id + '-btn');
+    const old = btn.textContent;
+    btn.textContent = 'Copied!';
+    setTimeout(() => {{ btn.textContent = old; }}, 1200);
+  }});
+}}
+</script>
+</head>
+<body>
+<h1>Authorization complete</h1>
+<p class="hint">state verified{pkce_note}. client_id=<code>{client_id}</code>, scope=<code>{scope}</code></p>
+
+<h2>Token response</h2>
+<pre>{token_response}</pre>
+
+{sections}
+
+<p><a href="/">&larr; start another flow</a></p>
+</body></html>
+"""
+
+TOKEN_SECTION = """
+<h2>{label}</h2>
+<div class="token-box">
+  <button class="copy-btn" id="{anchor}-btn" onclick="copyIt('{anchor}')">Copy</button>
+  <pre id="{anchor}">{token}</pre>
+</div>
+{claims_html}
+"""
+
+CLAIMS_BLOCK = """
+<p>Claims: {badges}</p>
+<pre>{claims}</pre>
+"""
+
+
+def _esc(value) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def _render_scope_checkboxes(scopes: list, current_scope_value: str) -> str:
+    if not scopes:
+        return ""
+    checked_words = set(current_scope_value.split())
+    items = []
+    for scope in scopes:
+        checked = "checked" if scope in checked_words else ""
+        items.append(
+            f'<label class="scope-item"><input type="checkbox" class="scope-checkbox" '
+            f'value="{_esc(scope)}" {checked}>{_esc(scope)}</label>'
+        )
+    return "".join(items)
+
+
+class _PendingFlow:
+    __slots__ = (
+        "verifier",
+        "token_endpoint",
+        "jwks_uri",
+        "client_id",
+        "scope",
+        "redirect_uri",
+        "nonce",
+        "created_at",
+    )
+
+    def __init__(self, verifier, token_endpoint, jwks_uri, client_id, scope, redirect_uri, nonce=None):
+        self.verifier = verifier
+        self.token_endpoint = token_endpoint
+        self.jwks_uri = jwks_uri
+        self.client_id = client_id
+        self.scope = scope
+        self.redirect_uri = redirect_uri
+        self.nonce = nonce
+        self.created_at = time.time()
+
+
+class DebuggerServer(HTTPServer):
+    def __init__(self, address, handler_cls, defaults: dict):
+        super().__init__(address, handler_cls)
+        self.defaults = defaults
+        self.pending: dict = {}
+        self.lock = threading.Lock()
+
+    def base_url(self) -> str:
+        host, port = self.server_address[:2]
+        display_host = "127.0.0.1" if host in ("0.0.0.0", "") else host
+        return f"http://{display_host}:{port}"
+
+    def sweep_expired(self) -> None:
+        cutoff = time.time() - PENDING_TTL_SECONDS
+        with self.lock:
+            expired = [state for state, flow in self.pending.items() if flow.created_at < cutoff]
+            for state in expired:
+                del self.pending[state]
+
+
+def _post_form(url: str, fields: dict) -> dict:
+    data = urllib.parse.urlencode(fields).encode("ascii")
+    req = urllib.request.Request(
+        url, data=data, method="POST", headers={"Content-Type": "application/x-www-form-urlencoded"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"token endpoint returned HTTP {exc.code}: {body}") from exc
+
+
+class Handler(BaseHTTPRequestHandler):
+    server: DebuggerServer  # type: ignore[assignment]
+
+    def log_message(self, fmt, *args):  # noqa: A002 - silence default request logging
+        return
+
+    def _send_html(self, body: str, status: int = 200) -> None:
+        encoded = body.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def _send_error_page(self, heading: str, message: str, status: int = 400) -> None:
+        self._send_html(
+            ERROR_PAGE.format(style=PAGE_STYLE, heading=_esc(heading), message=_esc(message)), status=status
+        )
+
+    def _send_json(self, payload: dict, status: int = 200) -> None:
+        encoded = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def do_GET(self):  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path == "/":
+            self._render_form()
+        elif parsed.path == "/discover":
+            self._handle_discover(urllib.parse.parse_qs(parsed.query))
+        elif parsed.path == "/callback":
+            self._handle_callback(urllib.parse.parse_qs(parsed.query))
+        else:
+            self._send_error_page("Not found", f"No route for {parsed.path}", status=404)
+
+    def _handle_discover(self, params: dict) -> None:
+        issuer = (params.get("issuer") or [""])[0].strip()
+        if not issuer:
+            self._send_json({"error": "missing issuer"}, status=400)
+            return
+        try:
+            metadata = fetch_metadata(issuer)
+        except Exception as exc:  # noqa: BLE001
+            self._send_json({"error": str(exc)}, status=502)
+            return
+        self._send_json(
+            {
+                "authorization_endpoint": metadata.get("authorization_endpoint", ""),
+                "token_endpoint": metadata.get("token_endpoint", ""),
+                "jwks_uri": metadata.get("jwks_uri", ""),
+                "scopes_supported": metadata.get("scopes_supported", []),
+            }
+        )
+
+    def do_POST(self):  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/start":
+            self._send_error_page("Not found", f"No route for {parsed.path}", status=404)
+            return
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length).decode("utf-8")
+        form = {k: v[0] for k, v in urllib.parse.parse_qs(body).items()}
+        self._handle_start(form)
+
+    def _render_form(self, values: dict = None) -> None:
+        d = dict(self.server.defaults)
+        d.update(values or {})
+
+        discovered_authorize_endpoint = discovered_token_endpoint = ""
+        scopes_supported: list = []
+        issuer = d.get("issuer", "").strip()
+        if issuer:
+            try:
+                metadata = fetch_metadata(issuer)
+                discovered_authorize_endpoint = metadata.get("authorization_endpoint", "")
+                discovered_token_endpoint = metadata.get("token_endpoint", "")
+                scopes_supported = metadata.get("scopes_supported", []) or []
+            except Exception:  # noqa: BLE001 - best-effort pre-fill; the page's own JS retries this
+                pass
+
+        scope_value = d.get("scope", "openid")
+        self._send_html(
+            FORM_PAGE.format(
+                style=PAGE_STYLE,
+                issuer=_esc(issuer),
+                authorize_endpoint=_esc(d.get("authorize_endpoint", "")),
+                token_endpoint=_esc(d.get("token_endpoint", "")),
+                discovered_authorize_endpoint=_esc(discovered_authorize_endpoint),
+                discovered_token_endpoint=_esc(discovered_token_endpoint),
+                client_id=_esc(d.get("client_id", "")),
+                scope=_esc(scope_value),
+                scope_checkboxes=_render_scope_checkboxes(scopes_supported, scope_value),
+                known_scopes_json=json.dumps(scopes_supported),
+                state=_esc(secrets.token_urlsafe(18)),
+                nonce=_esc(secrets.token_urlsafe(18)),
+                sel_s256="selected" if d.get("pkce_method", "S256") == "S256" else "",
+                sel_plain="selected" if d.get("pkce_method") == "plain" else "",
+                sel_none="selected" if d.get("pkce_method") == "none" else "",
+                verify_yes="selected" if d.get("verify_jwks", "yes") == "yes" else "",
+                verify_no="selected" if d.get("verify_jwks") == "no" else "",
+            )
+        )
+
+    def _handle_start(self, form: dict) -> None:
+        self.server.sweep_expired()
+
+        issuer = form.get("issuer", "").strip()
+        client_id = form.get("client_id", "").strip()
+        scope = form.get("scope", "").strip() or "openid"
+        pkce_method = form.get("pkce_method", "S256")
+        verify_jwks = form.get("verify_jwks", "yes") == "yes"
+
+        if not client_id:
+            self._send_error_page("Missing client_id", "client_id is required.")
+            return
+
+        authorize_endpoint = form.get("authorize_endpoint", "").strip()
+        token_endpoint = form.get("token_endpoint", "").strip()
+        jwks_uri = None
+
+        if not authorize_endpoint or not token_endpoint:
+            if not issuer:
+                self._send_error_page(
+                    "Missing issuer",
+                    "Provide an issuer to discover endpoints from, or fill in both endpoint overrides.",
+                )
+                return
+            try:
+                metadata = fetch_metadata(issuer)
+            except Exception as exc:  # noqa: BLE001
+                self._send_error_page("Discovery failed", str(exc))
+                return
+            authorize_endpoint = authorize_endpoint or metadata["authorization_endpoint"]
+            token_endpoint = token_endpoint or metadata["token_endpoint"]
+            jwks_uri = metadata.get("jwks_uri")
+
+        # state also keys this tool's own pending-flow bookkeeping (see _handle_callback), so
+        # unlike nonce it can't actually be sent empty even if the field was cleared - fall back
+        # to a fresh one in that case rather than silently breaking the callback correlation.
+        state = form.get("state", "").strip() or secrets.token_urlsafe(24)
+        nonce = form.get("nonce", "").strip()
+        verifier = challenge = None
+        if pkce_method != "none":
+            verifier = pkce.generate_verifier()
+            challenge = pkce.challenge_for(verifier, pkce_method)
+
+        redirect_uri = f"{self.server.base_url()}/callback"
+
+        query = {
+            "response_type": "code",
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "scope": scope,
+            "state": state,
+        }
+        if nonce:
+            query["nonce"] = nonce
+        if challenge:
+            query["code_challenge"] = challenge
+            query["code_challenge_method"] = pkce_method
+
+        for line in form.get("extra_params", "").splitlines():
+            line = line.strip()
+            if not line or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            query[key.strip()] = value.strip()
+
+        with self.server.lock:
+            self.server.pending[state] = _PendingFlow(
+                verifier=verifier,
+                token_endpoint=token_endpoint,
+                jwks_uri=jwks_uri if verify_jwks else None,
+                client_id=client_id,
+                scope=scope,
+                redirect_uri=redirect_uri,
+                nonce=nonce or None,
+            )
+        # Remember the last-used config as the new defaults, so reopening "/" (or the
+        # next flow) starts pre-filled with whatever was just tested.
+        self.server.defaults.update(
+            {
+                "issuer": issuer,
+                "client_id": client_id,
+                "scope": scope,
+                "pkce_method": pkce_method,
+                "verify_jwks": "yes" if verify_jwks else "no",
+            }
+        )
+
+        authorize_url = f"{authorize_endpoint}?{urllib.parse.urlencode(query)}"
+        self.send_response(302)
+        self.send_header("Location", authorize_url)
+        self.end_headers()
+
+    def _handle_callback(self, params: dict) -> None:
+        params = {k: v[0] for k, v in params.items()}
+        state = params.get("state")
+
+        with self.server.lock:
+            flow = self.server.pending.pop(state, None) if state else None
+
+        if "error" in params:
+            self._send_error_page(
+                "Authorization failed",
+                f"{params.get('error')}: {params.get('error_description', '')}",
+            )
+            return
+
+        if flow is None:
+            self._send_error_page(
+                "Unknown or expired state",
+                f"No pending flow for state={state!r}. It may have already been used, expired "
+                f"(pending flows are kept for {PENDING_TTL_SECONDS // 60} minutes), or this server "
+                "was restarted mid-flow. Start again from the form.",
+            )
+            return
+
+        code = params.get("code")
+        if not code:
+            self._send_error_page("Missing code", f"No 'code' in callback params: {params}")
+            return
+
+        token_request = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": flow.redirect_uri,
+            "client_id": flow.client_id,
+        }
+        if flow.verifier:
+            token_request["code_verifier"] = flow.verifier
+
+        try:
+            token_response = _post_form(flow.token_endpoint, token_request)
+        except RuntimeError as exc:
+            self._send_error_page("Token exchange failed", str(exc))
+            return
+
+        sections = []
+        for label, key in (("Access token", "access_token"), ("ID token", "id_token")):
+            token = token_response.get(key)
+            if not token:
+                continue
+            expected_nonce = flow.nonce if key == "id_token" else None
+            claims_html = self._render_claims(token, flow.jwks_uri, expected_nonce)
+            sections.append(
+                TOKEN_SECTION.format(
+                    label=_esc(label),
+                    anchor=key,
+                    token=_esc(token),
+                    claims_html=claims_html,
+                )
+            )
+        if token_response.get("refresh_token"):
+            sections.append(
+                TOKEN_SECTION.format(
+                    label="Refresh token",
+                    anchor="refresh_token",
+                    token=_esc(token_response["refresh_token"]),
+                    claims_html="",
+                )
+            )
+
+        pkce_note = "" if flow.verifier is None else " (PKCE verified by the server)"
+        self._send_html(
+            RESULTS_PAGE.format(
+                style=PAGE_STYLE,
+                pkce_note=pkce_note,
+                client_id=_esc(flow.client_id),
+                scope=_esc(flow.scope),
+                token_response=_esc(json.dumps(token_response, indent=2, ensure_ascii=False)),
+                sections="".join(sections),
+            )
+        )
+
+    def _render_claims(self, token: str, jwks_uri, expected_nonce: str = None) -> str:
+        try:
+            _header, payload = jwt_utils.decode(token)
+        except Exception:
+            return ""
+        badges = ['<span class="badge skip">not verified</span>']
+        if jwks_uri:
+            try:
+                ok = jwt_utils.verify_signature(token, jwks_uri)
+                badges = [
+                    '<span class="badge pass">signature PASS</span>'
+                    if ok
+                    else '<span class="badge fail">signature FAIL</span>'
+                ]
+            except Exception as exc:  # noqa: BLE001
+                badges = [f'<span class="badge fail">verify error: {_esc(exc)}</span>']
+        if expected_nonce:
+            actual_nonce = payload.get("nonce")
+            if actual_nonce == expected_nonce:
+                badges.append('<span class="badge pass">nonce PASS</span>')
+            else:
+                badges.append(
+                    f'<span class="badge fail">nonce FAIL (sent {_esc(expected_nonce)}, '
+                    f"got back {_esc(actual_nonce)})</span>"
+                )
+        return CLAIMS_BLOCK.format(
+            badges=" ".join(badges), claims=_esc(json.dumps(payload, indent=2, ensure_ascii=False))
+        )
+
+
+def run(host: str, port: int, defaults: dict, open_browser: bool) -> None:
+    server = DebuggerServer((host, port), Handler, defaults)
+    display_host = "127.0.0.1" if host in ("0.0.0.0", "") else host
+    url = f"http://{display_host}:{server.server_address[1]}/"
+    print(f"oauth2-debugger listening on {url}")
+    print("Press Ctrl+C to stop.")
+    if open_browser:
+        try:
+            webbrowser.open(url)
+        except webbrowser.Error as exc:
+            print(f"  (could not open a browser automatically: {exc}; open the URL above manually)")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()

oauth2_debugger-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "oauth2-debugger"
+version = "0.0.1"
+description = "Local debugger for the OAuth2/OIDC Authorization Code flow (state, scopes, PKCE)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = []
+
+[[project.authors]]
+name = "Yike Xiao"
+email = "kmter@live.com"
+
+[project.urls]
+Homepage = "https://github.com/Shawyeok/oauth2-debugger"
+Repository = "https://github.com/Shawyeok/oauth2-debugger"
+
+[project.optional-dependencies]
+verify = ["cryptography>=41"]
+
+[project.scripts]
+oauth2-debugger = "oauth2_debugger.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["oauth2_debugger"]