format/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a web-based Markdown to HTML converter application with secure Microsoft Azure AD authentication. The application requires authentication to access any functionality and validates tokens server-side for security.

Architecture

The application follows a secure client-server architecture with proper authentication:

• Frontend: Vanilla JavaScript with HTML/CSS, MSAL.js for authentication
• Backend: PHP with server-side JWT token validation
• Authentication: Microsoft Azure AD/Entra ID with PKCE flow and httpOnly cookies
• Security: Server-side authentication gate, JWT validation on all requests
• Markdown Processing: Client-side using marked.js library

Key Files

Authentication & Security

• AuthMiddleware.php - Authentication middleware for protecting endpoints
• JWTValidator.php - Custom JWT validation class for Azure AD tokens
• auth.php - Authentication endpoint for login/logout/status operations

Application Core

• index.php - Main application page with server-side authentication required
• process.php - Server-side endpoint with authentication protection
• config.php - PHP configuration and error reporting
• js/script.js - Enhanced client-side JavaScript with better error handling
• css/style.css - Application styling with Montserrat font

Authentication Flow

1. Page Access: All pages require authentication via AuthMiddleware->requireAuth()
2. Login Process: MSAL popup → token exchange → httpOnly cookie → page reload
3. Token Validation: JWT validated against Azure AD public keys on every request
4. Logout Process: Clear httpOnly cookie + MSAL logout → redirect

Authentication Configuration

• Client ID: 9079054c-9620-4757-a256-23413042f1ef
• Tenant ID: e519c2e6-bc6d-4fdf-8d9c-923c2f002385
• Flow: Authorization Code with PKCE (popup-based)
• Token Storage: httpOnly cookies for security
• Validation: Stateless JWT validation on each request

Security Features

• Server-side authentication gate on all pages and endpoints
• JWT signature validation using Azure AD public keys
• httpOnly cookies prevent XSS token theft
• Proper error handling with user-friendly messages
• No client-side security dependencies (removed CSS-based hiding)
• Token expiration and claim validation

Development Notes

• Dependencies: No build process required - uses CDN resources
• PHP Required: Full functionality requires PHP server with OpenSSL support
• Testing: Authentication can be tested locally with proper redirect URI configuration
• Error Handling: Authentication errors show clear messages to users
• Modern Features: Uses modern clipboard API with fallback for copying HTML