Skip to content

README.md

Latest commit

 

History

History
159 lines (110 loc) · 7.52 KB

README.md

File metadata and controls

159 lines (110 loc) · 7.52 KB

.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.