NPv.Auth.Application 0.5.0

NPv.Auth.Application

Application workflows for reusable NPv authentication realms.

The package provides CQS commands for self-registration, email confirmation, login, token refresh, logout, password recovery and reset, and administrative creation of confirmed accounts. It also includes realm configuration, password hashing, JWT generation, the IAuthClaimsProvider<TAccount> extension point, and an email-confirmation event handler with its email template.

HTTP endpoints and cookies belong to NPv.Auth.AspNetCore; persistence mapping belongs to NPv.Auth.Ef. This package does not create consumer-domain entities such as Actor or define their lifecycle.

Status

This package is at an early stage (0.x). Its public API and runtime behavior may change between minor versions.

Version 0.5.0 adds administrative confirmed-account provisioning and AuthErrors.EmailAlreadyExists. Existing workflow APIs are unchanged; no schema change is required.

Installation

dotnet add package NPv.Auth.Application --version 0.5.0

Applications normally consume this package through NPv.Auth.AspNetCore or a custom host adapter.

The host composes realm registrations, command bindings, the CQS/unit-of-work executor, repository and outbox implementations, and the services required by the chosen workflows. For confirmation emails it also supplies IMailSender and IEmailTemplateRenderer.

The email handler combines ClientBaseUrl with the conventional /account/register/confirm client route. A host can override AuthRealmOptions.EmailConfirmationPath only when its client uses another route.

Hosts that use assembly-scanned messaging can include AuthApplicationAssembly.Reference in their composition assembly list. This registers the standard auth event handlers without referring to their concrete types or namespaces.

Administrative provisioning

ProvisionConfirmedAuthAccountCommand<TAccount> accepts ProvisionConfirmedAuthAccountCommandContext<TAccount> with Email and Password in the NPv.Auth.Application.Registration namespace. The trusted host must authorize the caller before execution; the command performs no authorization. There is no generic HTTP endpoint for this operation.

Reference Application 0.5.0 directly to use this API. AddAuthRealm in NPv.Auth.AspNetCore 0.4.0 does not register it: the host must bind ICommand<ProvisionConfirmedAuthAccountCommandContext<TAccount>> to ProvisionConfirmedAuthAccountCommand<TAccount> and invoke it through the standard CQS/UoW executor. The command requires IGenericRepository, PasswordHasher, AuthRealmRegistry with the account type registered, and IOutbox. It returns Result, not an account or tokens.

TAccount derives from AuthAccountBase and must have a public parameterless constructor. Provisioning fills inherited auth fields only; custom required business fields remain the consumer's responsibility. See the Domain contract.

The command trims and lowercases email invariantly, validates its format and the current password contract (required, 6–16 characters) at application level, and creates an account with IsEmailConfirmed = true and IsBanned = false, ready for ordinary login and password recovery. Invalid input returns auth.invalid_credentials for the relevant property. Login does not normalize its input; supply the stored normalized email.

An existing email returns auth.email_already_exists without changing the account, password, confirmation or ban. A concurrent unique-constraint failure at commit remains an infrastructure exception handled by the host; retry finds the account through the ordinary lookup.

This use case is separate from self-registration: Registration.Enabled, AdminEmail, unconfirmed-account retries and ConfirmPassword remain part of RegisterAuthCommand. Provisioning starts no confirmation flow and creates no confirmation code, confirmation, recovery or refresh-token entity. It enqueues only AuthAccountRegisteredEvent in the outbox, with no AuthEmailConfirmationIssuedEvent or AuthAccountEmailConfirmedEvent. Consumers must not assume that registration always starts an email-confirmation flow; see the event's lifecycle semantics. It neither saves changes nor owns a transaction; the standard executor does.

Author's Note

This library grew out of my long-standing personal interest in structuring and publishing open source packages. Over time, I’ve revisited and refined earlier internal utilities and ideas, giving them a more consistent shape and preparing them for wider reuse. Along the way, I’ve also taken the opportunity to explore how open source distribution and licensing work in the .NET ecosystem.

It’s a small step toward something I’ve always wanted to try — sharing practical, minimal tools that reflect years of learning, experimentation, and refinement.

Hopefully, someone finds it useful.

Nikolai 😛

⚖️ License

MIT — you are free to use this in commercial and open-source software.