D&D Mapp: auth-client

The central identity and access management gateway for the D&D Mapp platform. This Angular-based client provides a secure and seamless interface for user authentication, authorization, and profile management across the entire ecosystem.

Features

The Auth Client serves as the entry point for all users of the D&D Mapp platform, handling critical identity flows and account security:

Identity & Onboarding

• User Registration: Streamlined sign-up process for new adventurers joining the platform.
• Secure Authentication: Robust login system supporting persistent sessions and secure token handling.
• Password Management: Fully integrated "Forgot Password" workflows, including email-initiated resets and secure credential updates.

Account Self-Service

• Profile Configuration: Manage personal details, display names, and public-facing profile information.
• Security Settings: User-driven account management, including email updates and multifactor authentication (MFA) setup (where applicable).
• Session Oversight: View and manage active sessions to ensure account integrity across multiple devices.

---

Getting Started

Prerequisites

This project uses mise-en-place to manage runtime versions and ensure environment consistency across development and CI/CD.

1. Install Mise to automatically manage:

   • Node.js: v24.13.1
   • pnpm: v10.29.3

2. mkcert: Required for local HTTPS. Install mkcert.

Local Environment Setup

1. Clone the repository:

   git clone https://github.com/dnd-mapp/auth-client.git
   cd auth-client

2. Install toolchains and dependencies:

   mise install
   pnpm install

3. Configure Local DNS:

   Add the following entry to your /etc/hosts (macOS/Linux) or C:\Windows\System32\drivers\etc\hosts (Windows) file:

   127.0.0.1  localhost.auth.dndmapp.dev
   

4. Generate SSL Certificates:

   Generate certificates using mkcert:

   mkcert -install
   pnpm gen:ssl-cert

---

Docker & Containerization

The application is containerized using Docker for consistent deployment across different architectures (amd64, arm64, arm/v7).

Using Docker Compose

To spin up the application quickly using the pre-built image:

docker compose -f .docker/compose.yaml up -d

The application will be accessible at http://localhost:4400.

Important

HTTPS Support: The default Docker configuration serves the application over standard HTTP via Nginx. For HTTPS in containerized environments, you must manually mount SSL certificates and update the Nginx configuration.

Building with Docker Buildx Bake

We use Docker Bake for high-performance, multi-platform builds. To build the image locally:

docker buildx bake -f .docker/docker-bake.hcl app

This will trigger a multi-stage build (using Node 24 and Nginx 1.29) and generate SBOM and provenance attestations.

---

Development Server

Run the following command to start the local development server with HTTPS:

pnpm start

Navigate to https://localhost.auth.dndmapp.dev:4400/. The application will automatically reload if you change any source files.

Tip

Troubleshooting Connection Errors: If you encounter "Privacy/SSL" errors or "Address Not Found" in your browser:

1. Ensure you have followed the Local Environment Setup steps to add 127.0.0.1 localhost.auth.dndmapp.dev to your system's hosts file.
2. Verify that you have run mkcert -install and generated the .pem files in the root directory.
3. If the browser still blocks the connection, try restarting the browser or clearing the HSTS cache for localhost.auth.dndmapp.dev.

---

Code Quality & Editor Setup

We use ESLint for logic, Stylelint for CSS/SCSS, and Prettier for consistent formatting.

Visual Studio Code

Settings are provided in .vscode/settings.json to automate "Fix on Save" for ESLint and Stylelint, ensuring all contributions meet the project's quality standards.

WebStorm

Stylelint

1. Open Settings.
2. Navigate to Languages & Frameworks > Style Sheets > Stylelint.
3. Check Enable.
4. Check Run stylelint --fix on save.

ESLint

1. Open Settings.
2. Navigate to Languages & Frameworks > JavaScript > Code Quality Tools > ESLint.
3. Select Automatic ESLint configuration.
4. Check Run eslint --fix on save.

Prettier

1. Open Settings.
2. Navigate to Languages & Frameworks > JavaScript > Prettier.
3. Select Automatic Prettier configuration.
4. Check Run on save.
5. Ensure the "Prettier package" points to the project's node_modules/prettier.

---

Scripts

• Start: pnpm start - Runs the dev server.
• Build: pnpm build - Compiles the application into the dist/auth-client/browser directory.
• Lint: pnpm lint - Runs ESLint to check for code quality issues.
• Lint Styles: pnpm stylelint - Runs Stylelint to check CSS/Tailwind rules.
• Format: pnpm format:write - Manually format all files using Prettier.

---

Tech Stack

• Framework: Angular 21
• Package Manager: pnpm
• Environment Manager: mise-en-place
• Styling: Tailwind CSS
• Linting: ESLint & Stylelint
• Code Formatting: Prettier
• Local HTTPS: mkcert
• Containerization: Docker & Nginx

---

Project Structure

The project follows a modular Angular architecture, optimized for Tailwind CSS v4 and clear separation of concerns.

auth-client/
├── .docker/                            # Docker configuration & Bake HCL
├── src/
│   ├── app/
│   │   ├── core/                       # Singleton services, guards, and root.component.ts
│   │   ├── features/                   # Auth flows (Login, Register, Reset Password)
│   │   └── shared/                     # Reusable UI components (Buttons, Inputs, Modals)
│   ├── index.html                      # Application host page
│   └── styles.css                      # Tailwind v4 entry point
├── .tool-versions                      # Version management (Mise)
└── package.json                        # Project dependencies

Key Architectural Notes:

• Root Component: Following a clean-core pattern, the main entry point has been renamed to root.component.ts and resides in src/app/core/root/.
• Tailwind CSS v4: This project uses the CSS-first configuration approach of Tailwind v4. Theme variables and customizations are defined directly in src/styles.css using the @theme block, eliminating the need for a separate tailwind.config.js.
• Environment Management: We use .tool-versions to ensure that mise loads the exact versions of Node.js and pnpm required for this project.

---

Deployment

To prepare the application for a production environment, you must generate a production build. This process optimizes the bundle size and minifies the code for better performance.

Building for Production

Run the following command to create a production-ready build:

pnpm build

Build Output

Once the build process is complete, the compiled files will be located in the following directory:

dist/auth-client/browser

These files are static and can be deployed to any web server (e.g., Nginx, Apache, or cloud hosting services like Vercel, Netlify, or AWS S3).

Note: Ensure your web server is configured to redirect all requests to index.html to support Angular's client-side routing.

---

License

Copyright © 2026 NoNamer777. All rights reserved.

This software and its associated documentation are proprietary. Access to and use of this software is strictly governed by the terms of the LICENSE file included in this repository.

No part of this project may be reproduced, distributed, or transmitted in any form or by any means, including copying or creating derivative works, without the prior written permission of the author.

For inquiries regarding licensing or permissions, please contact the author via the GitHub repository.

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on our code of conduct, branching strategy, and the process for submitting pull requests.

As this project is proprietary, please ensure you have received authorization before contributing.