CodeLogic.TwoFactorAuth 5.0.113-preview

This is a prerelease version of CodeLogic.TwoFactorAuth.

This package has a SemVer 2.0.0 package version: 5.0.113-preview+6deff0c.

There is a newer prerelease version of this package available.
See the version list below for details.

dotnet add package CodeLogic.TwoFactorAuth --version 5.0.113-preview

NuGet\Install-Package CodeLogic.TwoFactorAuth -Version 5.0.113-preview

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="CodeLogic.TwoFactorAuth" Version="5.0.113-preview" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="CodeLogic.TwoFactorAuth" Version="5.0.113-preview" />
                    

                            Directory.Packages.props

<PackageReference Include="CodeLogic.TwoFactorAuth" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add CodeLogic.TwoFactorAuth --version 5.0.113-preview

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: CodeLogic.TwoFactorAuth, 5.0.113-preview"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package CodeLogic.TwoFactorAuth@5.0.113-preview

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=CodeLogic.TwoFactorAuth&version=5.0.113-preview&prerelease
                    

                            Install as a Cake Addin

#tool nuget:?package=CodeLogic.TwoFactorAuth&version=5.0.113-preview&prerelease
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CodeLogic.TwoFactorAuth

TOTP two-factor authentication with QR-code generation for CodeLogic 5 — compatible with Google Authenticator, Authy, and 1Password.

Implements RFC 6238 time-based one-time passwords over Otp.NET and renders provisioning QR codes with QRCoder. Two services are exposed: an authenticator (generate/validate codes) and a QR-code generator.

Install

dotnet add package CodeLogic.TwoFactorAuth

Quick start

await Libraries.LoadAsync<TwoFactorAuthLibrary>();
await CodeLogic.ConfigureAsync();
await CodeLogic.StartAsync();

var tfa = Libraries.Get<TwoFactorAuthLibrary>();

// 1. Enrol: create a key bound to issuer + user (fresh Base32 secret)
TwoFactorKey key = tfa.GenerateNewKey("MyApp", "user@example.com");
//    persist key.SecretKey alongside the user record

// 2. Show a QR code for the authenticator app
Result<string> qr = tfa.GenerateQrCodeDataUri(key);   // data:image/png;base64,...
if (qr.IsSuccess) { /* <img src="qr.Value"> */ }

// 3. Verify a code the user typed
TotpValidationResult check = tfa.ValidateTotp("123456", key.SecretKey);
if (check.IsValid) { /* grant access */ }

Features

Secret generation — cryptographically random Base32 TOTP secrets (GenerateSecretKey).
Provisioning — GenerateNewKey(issuer, user) returns a TwoFactorKey with a standard otpauth:// ProvisioningUri that carries the configured period.
Generate & validate — GenerateTotpCode / ValidateTotp with a configurable time step and drift window; validation returns a TotpValidationResult with the matched absolute time step (MatchedWindow, a long, for replay tracking) and the drift in steps (WindowOffset).
Lifetime helpers — GetSecondsUntilExpiry() and GetCurrentTimeWindow().
QR rendering — PNG / BMP bytes, Base64, data URI, and save-to-file, with configurable module size and error-correction level.
Events — SecretKeyGeneratedEvent and TotpValidatedEvent on the CodeLogic event bus.

Configuration

Auto-generated on first run as config.twofactorauth.json. Keys are camelCase and matched case-sensitively, so a PascalCase key is ignored and its default stays active:

{
  "enabled": true,
  "timeStepSeconds": 30,
  "windowSize": 1,
  "qrCodeModuleSize": 20,
  "errorCorrectionLevel": "q"
}

Setting	Default	Description
`Enabled`	`true`	Master switch; when `false` the services aren't created and health reports disabled.
`TimeStepSeconds`	`30`	TOTP time step (1–300); must match the authenticator app.
`WindowSize`	`1`	Steps before/after the current window accepted (0–10); `1` ≈ ±30s drift.
`QrCodeModuleSize`	`20`	Pixel size of each QR module (1–100).

Values outside these ranges fail configuration validation. | ErrorCorrectionLevel | Q | L (~7%), M (~15%), Q (~25%), H (~30%). |

Documentation

Full guide: CL.TwoFactorAuth documentation

Requirements

CodeLogic 5.0+ · .NET 11
Otp.NET 1.x · QRCoder 1.x

License

MIT — see LICENSE.

Product	Compatible and additional computed target framework versions.
.NET	net11.0 is compatible.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net11.0
- CodeLogic (>= 5.0.0-preview && < 6.0.0)
- Otp.NET (>= 1.4.1)
- QRCoder (>= 1.8.1)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on CodeLogic.TwoFactorAuth:

Package	Downloads
CodeLogic.WebLogic Web application toolkit for CodeLogic 4 — routing, templates, forms, an ordered security pipeline, auth flows and realtime. No third-party dependencies beyond CodeLogic.*.	570

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
5.0.116-preview	0	11/1/2026
5.0.115-preview	39	11/1/2026
5.0.113-preview	30	10/31/2026
4.9.98	500	10/25/2026
4.8.93	61	9/23/2026
4.8.87	73	9/13/2026
4.8.85	55	9/12/2026
4.6.72	227	6/20/2026
4.6.69-preview	60	6/20/2026
4.5.2	133	5/24/2026
4.5.2-preview.68	88	6/20/2026
4.5.1	182	5/24/2026
4.5.1-preview.56	127	5/24/2026
4.4.2-preview.53	81	5/24/2026
4.4.1	125	5/24/2026
4.0.5	131	5/15/2026
4.0.4	139	5/9/2026
4.0.3	133	5/9/2026
3.3.1	641	4/18/2026
3.3.0	129	4/18/2026

# CL.TwoFactorAuth — Changelog

All notable changes to **CodeLogic.TwoFactorAuth** are documented here. Versions follow
[Semantic Versioning](https://semver.org/).

## 5.0 (unreleased)

### Breaking

- Targets **.NET 11** (`net11.0`) and requires **CodeLogic 5.0** (`[5.0.0, 6.0.0)`). On .NET 10, stay on
4.9.x. CodeLogic 5 makes `Result<T>` / `Result` C# 15 unions and `Error` a closed record with
kind subtypes (`NotFoundError`, `ValidationError`, ...). Results can now be matched exhaustively
with `switch`.
- **`TotpValidationResult.MatchedWindow` is a `long?` holding the absolute time step** that matched
(Unix time / `TimeStepSeconds`, what Otp.NET reports and what `GetCurrentTimeWindow()` returns). It
was an `int?` documented as a drift offset, and the narrowing could overflow with short periods. Use it
for replay tracking (store the last accepted step per user, atomically). `TotpValidatedEvent.MatchedWindow`
is `long?` too, and `TotpValidationResult.Valid(...)` takes `(long? matchedWindow, int? windowOffset)`.
- **Configuration validation enforces the documented upper limits:** `TimeStepSeconds` 1–300,
`WindowSize` 0–10, `QrCodeModuleSize` 1–100. Only the lower bounds were checked before, so a config with
larger values loaded and now fails validation.

### Added

- `TotpValidationResult.WindowOffset` (`int?`): the drift in steps (0 = current step, -1 = previous, +1 = next).
- `ValidateTotp(code, secretKey, DateTime timestampUtc, userId)` validates as of a given moment.
- `TwoFactorKey.PeriodSeconds` (default 30) and the `MinTimeStepSeconds` / `MaxTimeStepSeconds` /
`MaxWindowSize` / `MaxQrCodeModuleSize` constants on `TwoFactorAuthConfig`.

### Fixed

- **The provisioning URI carries the time step.** `ProvisioningUri` omitted `period`, so with a
non-default `TimeStepSeconds` the authenticator app generated 30-second codes the server rejected.
`GenerateNewKey` now sets `PeriodSeconds` from the configuration and the URI always ends in
`&period=<seconds>`, which also changes the QR code content.

### Documentation

- Configuration examples use the camelCase keys the CodeLogic loader reads (PascalCase keys were ignored).

### Changed

- Package versions are pinned (Otp.NET 1.4.1, QRCoder 1.8.1) instead of floating (`1.*`).

## 2026-10-24

### Changed

- Requires **CodeLogic 4.9+**. The official libraries move to the 4.9 line together with the framework,
whose live config changes the stateful libraries now use. No API changes in this library.

## 2026-09-12

### Changed

- Unified the version line with the CodeLogic framework on **4.8.x**. Every official
library and the framework now share one `major.minor`, so a given `4.8.<patch>`
means the same generation across all packages.
- `version.txt` moved from `4.6` to `4.8`. The patch component remains the CI run
number, composed at pack time; `AssemblyVersion` stays pinned at `Major.Minor.0.0`
(now `4.8.0.0`) so every patch in the line loads interchangeably.

## 2026-06-20

### Documentation

- Full rewrite of the README and the `docs/libs/twofactorauth.md` guide to the
shared house style: a concise, NuGet-rendered README (badges, tagline, install,
quick start, features, configuration table + JSON, requirements) and a single
deep documentation page covering the enrolment flow, sign-in validation, the
`Authenticator` and `QrCode` services, the `TwoFactorKey` /
`TotpValidationResult` shapes, configuration, events, and the health check.
No API changes.

## [4.5.2] — 2026-06-20

### Documentation

- Corrected the README and the security guide to match the shipping API. The
previous docs referenced members and config keys that do not exist
(`GenerateSecret`, `Validate(secret, token)`, `GetOtpAuthUri`, backup-code
helpers, and the `Issuer`/`SecretKeyLength`/`TokenValiditySeconds`/
`AllowedClockSkewSeconds`/`QrCodeSize` settings).
- Documented the real configuration keys: `Enabled`, `TimeStepSeconds`,
`WindowSize`, `QrCodeModuleSize`, and `ErrorCorrectionLevel`
(`L`/`M`/`Q`/`H`).
- Documented the `Authenticator` and `QrCode` services and their full surface:
`GenerateSecretKey`, `GenerateNewKey`, `GenerateTotpCode`, `ValidateTotp`
(incl. the optional `userId` argument and the `TotpValidationResult` shape),
`GetSecondsUntilExpiry`, `GetCurrentTimeWindow`, and the QR outputs
`GenerateQrCodePng` / `GenerateQrCodeBmp` / `GenerateQrCodeBase64` /
`GenerateQrCodeDataUri` / `SaveQrCodeToFile`.
- Documented the `TwoFactorKey.ProvisioningUri` (`otpauth://`) property, the
`SecretKeyGeneratedEvent` / `TotpValidatedEvent` bus events, and the actual
health-check behavior (live TOTP key generation).

## [4.5.0] — 2026-05-24

### Changed

- **Unified versioning.** All CodeLogic.Libs now share a single version line
controlled by `version.txt` in the repo root. This is a version alignment
release — no functional changes to this library.
## [4.0.4] — 2026-04-16

### Changed

- README + manifest refresh for the v4 baseline. No functional changes vs 4.0.3.
- `LibraryManifest.Version` now reads from assembly metadata.

## [4.0.2] — 2026-04-09

### Changed

- Annotated 2FA configuration with `[ConfigField]` for the admin UI surface.
- Aligned with the v4 baseline across all libraries.

## [4.0.0] — 2026-04-09

Major rewrite. Republished as v4.0.0 to reset the version line under the
unified v4 baseline. TOTP-based 2FA with QR code generation, backup codes,
and a CodeLogic-native flow for Google Authenticator / Authy / 1Password.

### Notes

- Earlier history is retained in the
[git log](https://github.com/zyntal-com/CodeLogic.Libs/commits/main/CL.TwoFactorAuth).