Skip to content

CLAUDE.md

Latest commit

 

History

History
72 lines (61 loc) · 3.68 KB

CLAUDE.md

File metadata and controls

72 lines (61 loc) · 3.68 KB

OIDC Debugging Tool

Project Overview

An OIDC/Auth0 debugging and educational tool built with Next.js (App Router). It allows users to configure Auth0 settings dynamically and step through OAuth2/OIDC flows interactively, inspecting every request and response.

Tech Stack

  • Next.js 16 with App Router and src/ directory
  • @auth0/nextjs-auth0 for the Token Vault flow (SDK-based Auth0 client)
  • shadcn/ui + Tailwind CSS v4 for UI components
  • TypeScript throughout

Architecture

  • Auth0 config is stored in localStorage (client) and .oidc-debug-config.json (server) for dynamic configuration
  • Four flows available:
    • Auth Code + PKCE — manual HTTP calls, PKCE verifier and state in httpOnly cookies, pauses at callback for user to trigger token exchange
    • Client Credentials — manual HTTP calls for machine-to-machine token requests
    • Device Flow — manual HTTP calls with polling for device authorization
    • Token Vault — uses @auth0/nextjs-auth0 SDK to demonstrate Federated Credentials / Token Vault connections
  • The first three flows use manual HTTP calls via API routes for full transparency
  • API routes return { request, response } objects so the UI can display both the outgoing request and incoming response
  • No middleware - everything runs in Node.js runtime
  • Environment variables AUTH0_SECRET and APP_BASE_URL configure the Auth0 SDK (see .env.example)

Commands

  • npm run dev - Start dev server (Turbopack)
  • npm run build - Production build
  • npm run lint - ESLint

Key Files

Lib

  • src/lib/config-store.ts - Server-side config read/write (.oidc-debug-config.json)
  • src/lib/auth0.ts - PKCE + authorize URL generation helpers
  • src/lib/auth0-client.ts - Auth0 SDK client factory (for Token Vault flow)
  • src/lib/jwt.ts - JWT decode utility (manual Base64 decoding)
  • src/lib/types.ts - Shared TypeScript types (OIDCConfig, FlowStep, HttpRequestInfo, etc.)
  • src/lib/utils.ts - Utility functions (cn helper)

Hooks

  • src/hooks/use-config.ts - React hook for reading/writing Auth0 config

Pages

  • src/app/config/page.tsx - Configuration page
  • src/app/flows/auth-code/page.tsx - Auth Code + PKCE flow (most complex)
  • src/app/flows/client-credentials/page.tsx - Client Credentials flow
  • src/app/flows/device-flow/page.tsx - Device Authorization flow
  • src/app/flows/token-vault/page.tsx - Token Vault / Federated Credentials flow
  • src/app/tokens/page.tsx - JWT inspector (paste any token)

API Routes

  • src/app/api/auth-code/ - start, callback, exchange routes
  • src/app/api/client-credentials/route.ts - Client credentials token request
  • src/app/api/device-flow/ - start, poll routes
  • src/app/api/token-vault/ - connections, enable-connection, exchange, mgmt-token, test-api routes
  • src/app/api/auth-config/route.ts - Config read/write API
  • src/app/auth/[...auth0]/route.ts - Auth0 SDK route handler (login/callback/logout)
  • src/app/me/[...path]/route.ts - Proxy route for Auth0 /me/ API

Custom Components

  • src/components/http-request-display.tsx - Renders outgoing HTTP requests
  • src/components/http-response-display.tsx - Renders incoming HTTP responses
  • src/components/token-inspector.tsx - Decoded JWT display
  • src/components/code-block.tsx - Syntax-highlighted code block
  • src/components/nav.tsx - Navigation bar

Conventions

  • Use "use client" directive for interactive pages
  • Wrap pages using useSearchParams() in <Suspense>
  • API routes return { request, response } objects so the UI can display both
  • shadcn/ui components in src/components/ui/
  • Custom components in src/components/
  • Config file .oidc-debug-config.json is gitignored (contains secrets)