.NET 10 Web API Controllers Auth Starter

A production-grade, hardened, enterprise-ready .NET 10 Web API template featuring traditional Controllers, PostgreSQL 18, and JWT Bearer Authentication out of the box.

This repository implements the Modern Multi-Project Directory Layout, isolating packaging orchestration metadata from the runtime blueprint workspace to eliminate template pollution.

---

🚀 Key Architectural Features

• Advanced Cryptographic Armor: Features built-in timing-attack resistance using automated dummy-hash verification passes for non-existent user identities.
• Brute-Force Account Lockout: Native progressive account freezes (5 consecutive failed attempts trigger an automatic 15-minute penalty window) executed before high-CPU hashing passes.
• Modern Database Topology: Pre-mapped PostgreSQL 18 Alpine containment layers incorporating sparse indexes for performance-optimized token lookups.
• Strict Role-Based Authorization (RBAC): Type-safe global enum role mappings cleanly stored inside database columns as strings and transmitted securely inside signed JWT claims.
• Automated Bootstrapping: Self-executing template scripts that automatically map environmental variations, duplicate structural templates, and alter internal compiler namespace configurations on demand.

---

🛠️ Tech Stack & Dependencies

Component	Technology	Version
Runtime Layer	.NET SDK	10.0
Database Engine	PostgreSQL (Alpine Core)	18.0
ORM Interface	Entity Framework Core	10.0
Password Hashing	BCrypt.Net-Next	Latest Stable
Token Middleware	Microsoft.AspNetCore.Authentication.JwtBearer	10.0

---

📖 Example Usage Patterns

You can consume and execute this starter template using two primary installation methods depending on whether you are staging it for private internal teams or distributing it globally.

Method A: The GitHub Direct Approach (Zero-Registry Flow)

Perfect for internal development loops, corporate teams sharing private infrastructure, or developers pulling code directly from an active development branch without setting up a NuGet ecosystem.

# 1. Pull and register the template directly from the source repository
dotnet new install https://github.com/alexmonteil/webapi-controllers-auth-starter

# 2. Generate a brand-new project workspace using your project namespace
dotnet new webapi-controllers-auth-starter -n HealthTracker.Api

# 3. Enter the generated codebase directory
cd HealthTracker.Api

# 4. Spin up your local dependencies and launch the system
docker compose up -d
dotnet ef database update
dotnet run

Method B: The NuGet Package Approach (Enterprise Standard)

The standard approach for public-facing utilities. This delivers a production-grade developer experience by allowing your code blueprint to be consumed natively as a global .NET SDK CLI command extension.

# 1. Install the officially indexed package artifact globally on your machine
dotnet new install WebAPI.Controllers.Auth.Starter

# 2. Scaffold your secure controller architecture stack instantly
dotnet new webapi-controllers-auth-starter -n BillingSystem.Api

# 3. Navigate into your clean workspace
cd BillingSystem.Api

# 4. Launch your self-contained database cluster and execute the system
docker compose up -d
dotnet ef database update
dotnet run

---

⚙️ Zero-Configuration Local Launch

Once you have scaffolded your fresh project using either method above, complete these minor steps inside the newly generated repository folder to launch your workspace:

1. Verify Your Environment Secret Config

Your local .env configuration file is automatically generated by the template engine script from the underlying .env.example blueprint. Open it up to inspect your connection strings or customize port bindings:

Configuration Key	Purpose / Target Scope	Default Value
APP_NAME	Application name	placeholder_app_name
JWT_SECRET_KEY	Cryptographic signature lock parameter	64-Character Safe Placeholder
JWT_ISSUER	Token issuer claim value	placeholder_issuer
JWT_AUDIENCE	Token audience claim value	placeholder_audience
DB_NAME	Target database catalog tracking title	placeholder_db
DB_USER	Primary administrative database profile	placeholder_user
DB_PASSWORD	Security credential block entry key	local_dev_password
DB_HOST	Local database container network alias	placeholder_localhost
DB_PORT	Local database container port mapping	placeholder_port
MailSettings__MailAdress	SMTP sender email address for verification emails	placeholder_mailaddress
MailSettings__AppName	App name for the sender in verification emails	placeholder_appname
MailSettings__MailPassword	Password for the sender email account
MailSettings__MailHost	SMTP server host for sending verification emails	placeholder_smtp_host
MailSettings__MailPort	SMTP server port for sending verification emails	placeholder_smtp_port

2. Up the Database Infrastructure

Your compose.yaml file natively references your local .env keys. Spin up the underlying PostgreSQL 18 container in decoupled background mode:

docker compose up -d

3. Run EF Migrations & Execute

Build your database schemas from your fluent mappings, compile the application, and launch the engine:

dotnet ef database update
dotnet run

Your developer documentation UI will instantly mount and expose your secure endpoints at http://localhost:5000 or https://localhost:5001.

---

🔒 Security Posture & Endpoint Map

All authentication mutations operate on strict Idempotent HTTP POST constraints to bypass corporate email safety bots and pre-fetching client scrapers.

POST  /api/auth/register             <- Create new identity signature
POST  /api/auth/login                <- Verify credentials & emit JWT access token
POST  /api/auth/verify               <- Confirms email authenticity via token matching
POST  /api/auth/resend-verification  <- Generates a fresh activation token payload

🛡️ Security Note on Side-Channel Timing Exploits

The /api/auth/login endpoint uses fixed-time string evaluations. If a client queries an unregistered email address, the engine computes a deep password-hashing sequence against a static dummy record. Response intervals remain identical across valid and invalid records, making it impossible for automated systems to harvest valid user emails by measuring server latency down to the millisecond.

---

🔄 Lifecycle Management: Updating & Uninstalling

If you add new features to your underlying blueprint template source code and need to refresh or purge the local template development cache on your machine environment:

# View all custom third-party templates registered on your machine
dotnet new list

# Scan for and apply downstream updates to your globally installed templates
dotnet new update

# Completely remove the template from your local machine's SDK layer
dotnet new uninstall WebAPI.Controllers.Auth.Starter

# Or if you originally registered it directly from a GitHub repository link:
dotnet new uninstall https://github.com/alexmonteil/webapi-controllers-auth-starter

---

📄 License

Distributed under the MIT License. See LICENSE for more information. Anyone is free to use, modify, distribute, or bundle this software template in commercial or private environments without restrictions.