Skip to content

PROJECT-INDEX.md

Latest commit

 

History

History
253 lines (177 loc) · 10.1 KB

PROJECT-INDEX.md

File metadata and controls

253 lines (177 loc) · 10.1 KB
Raw

LDAP Selfservice Password Changer - Project Index

Complete project knowledge base and documentation map.

🎯 Quick Navigation by Role

👨‍💻 For Developers

  1. Start: Development Guide
  2. Code: Code Structure Reference
  3. API: JSON-RPC API Reference
  4. Test: Testing Guide

🚀 For DevOps/SRE

  1. Deploy: Deployment Guide
  2. Config: Environment Variables
  3. Monitor: Architecture Overview
  4. Security: Security Documentation

♿ For Accessibility/QA

  1. WCAG: Accessibility Guide
  2. Test: Testing Procedures
  3. Validate: WCAG Compliance Matrix

🏗️ For Architects

  1. Design: Architecture Overview
  2. Decisions: Architecture Decision Records
  3. Security: Security Architecture
  4. Code: Package Structure

📚 Complete Documentation Map

Core Documentation (docs/)

Document Purpose Audience
README Documentation index All
API Reference JSON-RPC API specification Developers, Integrators
Development Guide Setup and workflows Developers
Testing Guide Test strategies and coverage Developers, QA
Accessibility Guide WCAG 2.2 AAA compliance Accessibility, QA
Architecture System design overview Architects, Developers
Code Structure Internal package reference Developers
Deployment Production deployment DevOps, SRE
Security Security architecture Security, DevOps

Architecture Decision Records (docs/adr/)

ADR Title Status Date
ADR-0001 Standardize Form Field Names ✅ Accepted 2024-10-06
ADR-0002 Password Reset Functionality ✅ Accepted 2024-10-07
ADR-0003 Configurable Reset Email Templates ✅ Accepted 2026-07-22

Supplementary Documentation (docs/)

Document Purpose Audience
Onboarding Checklist Progressive learning path for new developers New developers
Documentation Maintenance Guide Keeping documentation accurate as code evolves Maintainers
Security Assessment Security assessment report (2025-10-09) Security, DevOps
Security Assessment (Revised) Revised security assessment report Security, DevOps

🔍 Project Overview

What This Project Does

LDAP Selfservice Password Changer provides:

  1. Self-Service Password Changes - Authenticated users change their LDAP/AD passwords
  2. Password Reset via Email - Unauthenticated password recovery with secure tokens
  3. Accessible Web Interface - WCAG 2.2 AAA compliant with adaptive themes
  4. JSON-RPC API - Programmatic integration for custom frontends

Key Features

✅ Security: LDAPS, rate limiting, cryptographic tokens, minimal attack surface ✅ Accessibility: WCAG 2.2 AAA, screen reader support, keyboard navigation, adaptive density ✅ Modern UX: Dark mode, responsive design, real-time validation, password manager support ✅ Developer Friendly: Single binary, embedded assets, comprehensive tests, hot reload

Technology Stack

Layer Technology Version
Backend Go 1.26 (go.mod)
Web Framework Fiber v3.4.0 (github.com/gofiber/fiber/v3)
Frontend TypeScript ~6.0.3 (package.json)
CSS Tailwind CSS ^4.3.2 (package.json)
Build Bun no version pinned
Testing testify v1.11.1 (go.mod)

🏗️ Code Structure

ldap-selfservice-password-changer/
├── internal/              # Internal packages (not exported)
│   ├── email/             # SMTP service for password reset emails
│   ├── options/           # Application configuration
│   ├── ratelimit/         # Rate limiting middleware
│   ├── resettoken/        # Token generation and storage
│   ├── rpchandler/        # JSON-RPC handlers
│   ├── validators/        # Password validation rules
│   └── web/               # Web server and static assets
│       ├── static/        # Compiled JS, CSS, icons
│       │   └── js/        # TypeScript sources
│       └── templates/     # Go html/template components
│           ├── atoms/     # Basic UI elements
│           └── molecules/ # Composite components
├── docs/                  # Official documentation
│   └── adr/               # Architecture Decision Records
├── main.go                # Application entry point
├── go.mod                 # Go dependencies
├── package.json           # Node.js dependencies
├── tsconfig.json          # TypeScript configuration
└── compose.yml            # Docker Compose setup

See Code Structure Documentation for detailed package descriptions.

🚀 Quick Start

Development Setup (5 minutes)

# 1. Clone repository
git clone https://github.com/netresearch/ldap-selfservice-password-changer.git
cd ldap-selfservice-password-changer

# 2. Install dependencies
bun install

# 3. Copy environment template
cp .env.local.example .env.local

# 4. Start development server with hot reload
bun run dev

Server runs on http://localhost:3000 (default)

Full setup guide: Development Guide - Initial Setup

Production Deployment

# Using Docker
docker pull ghcr.io/netresearch/ldap-selfservice-password-changer:latest
docker run -p 3000:3000 --env-file .env ldap-selfservice-password-changer

# Or build from source
bun run build:assets
go build -o ldap-selfservice-password-changer
./ldap-selfservice-password-changer

Full deployment guide: Deployment Documentation

🧪 Testing

Run all tests:

go test ./... -cover

Current coverage: tracked by Codecov, not restated here — see the codecov badge and dashboard. Hardcoded per-package percentages in Markdown go stale within a release; the command above prints the authoritative local numbers.

See Testing Guide for comprehensive testing documentation.

🔐 Security

Security Features

  • LDAPS Support: Encrypted LDAP connections
  • Rate Limiting: 10 requests/hour per IP (hardcoded) on both endpoints, plus 3 requests/hour per identifier for reset requests (configurable)
  • Cryptographic Tokens: 256-bit secure token generation
  • No Password Storage: Passwords never persisted
  • Input Validation: Client and server-side validation

There is no CSRF protection; see WAF-02 in docs/security-assessment-revised-2025-10-09.md.

See Security Documentation for threat model and security architecture.

♿ Accessibility

WCAG 2.2 Level AAA Compliant

✅ 7:1 contrast ratios (AAA) ✅ Adaptive density modes (comfortable/compact) ✅ Full keyboard navigation ✅ Screen reader optimized ✅ System preference detection (theme, motion, contrast)

See Accessibility Guide for compliance matrix and testing procedures.

📖 Additional Resources

Official Links

External Documentation

Contributing

See README.md for contributing guidelines.

📝 Document Maintenance

Last Updated: 2026-07-23 Maintained By: Development Team Update Frequency: Per release + major changes

To update this index: Add new documents to appropriate section with description and audience.

For questions or suggestions about documentation, open an issue on GitHub.