LowCodeHub.OTP 0.0.12

LowCodeHub.OTP

A provider-neutral OTP flow library for .NET. It gives applications a standard SendAsync, VerifyAsync, and ResendAsync workflow with reference ids, hashed OTP storage, expiry, resend cooldowns, max resend limits, max verification attempts, and replay prevention.

Installation

dotnet add package LowCodeHub.OTP

Quick Start

using LowCodeHub.OTP.Extensions;

builder.Services
    .AddOtp(builder.Configuration)          // binds the "Otp" section
    .AddOtpRedis(builder.Configuration)     // binds "Otp:Redis"; omit to use the in-memory store
    .AddOtpSender<SmsOtpSender>();          // your delivery provider

{
  "Otp": {
    "HashPepper": "<at least 16 characters, from a secret store>",
    "Redis": { "ConnectionString": "localhost:6379" }
  }
}

public sealed class SmsOtpSender(ISmsClient sms) : IOtpSender
{
    public Task SendAsync(OtpDeliveryMessage message, CancellationToken cancellationToken = default)
        => sms.SendAsync(message.Recipient, $"Your code is {message.Code}", cancellationToken);
}

Every registration method also has a lambda form (AddOtp(o => ...), AddOtpRedis(o => ...)), and AddOtp(configuration, o => ...) binds first and then applies the lambda. All options are validated at startup.

Send, Verify, Resend

app.MapPost("/otp/send", async (IOtpService otp, SendOtpBody body, CancellationToken ct) =>
{
    try
    {
        OtpSendResult result = await otp.SendAsync(new OtpSendRequest
        {
            Recipient = body.Phone,
            Channel = "sms",
            Purpose = "login"
        }, ct);

        return Results.Ok(new { result.ReferenceId, result.ExpiresAtUtc, result.ResendAvailableAtUtc });
    }
    catch (OtpSendThrottledException ex)
    {
        return Results.Problem(
            statusCode: StatusCodes.Status429TooManyRequests,
            detail: ex.Message,
            extensions: new Dictionary<string, object?> { ["retryAfterUtc"] = ex.RetryAfterUtc });
    }
});

app.MapPost("/otp/verify", async (IOtpService otp, OtpVerifyRequest request, CancellationToken ct) =>
{
    OtpVerifyResult result = await otp.VerifyAsync(request with { Purpose = "login" }, ct);
    if (!result.Succeeded)
        return Results.BadRequest(new { reason = result.FailureReason.ToString() });

    // result.Recipient is the verified phone/email: sign that user in here.
    return Results.NoContent();
});

app.MapPost("/otp/resend", async (IOtpService otp, OtpResendRequest request, CancellationToken ct) =>
{
    OtpResendResult result = await otp.ResendAsync(request, ct);
    return result.Succeeded ? Results.Ok(result) : Results.BadRequest(result);
});

• OtpVerifyResult.Recipient, Channel, Purpose and ConsumedAtUtc are set only on success, so a failed result never reveals who a reference id belongs to. On success, use Recipient to decide who is signed in — the reference id alone is not an identity.
• Set OtpVerifyRequest.Purpose to the purpose your endpoint expects; a code issued for another purpose is reported as NotFound and left untouched.
• SendAsync throws OtpSendThrottledException (an InvalidOperationException) when it cannot send yet: the previous code was sent less than ResendCooldown ago, or the recipient used up MaxResendCount and must wait for the current code to expire. RetryAfterUtc says when to try again.
• After the cooldown, SendAsync for the same recipient/channel/purpose supersedes the active code (the old reference id stops working) and counts as a resend, so repeated sends cannot bypass MaxResendCount. A consumed or expired code never blocks a new send.
• Reference ids are opaque tokens of 1–128 characters [A-Za-z0-9_.-]. Malformed ids passed to VerifyAsync/ResendAsync are answered as NotFound; a malformed caller-supplied OtpSendRequest.ReferenceId throws ArgumentException.
• OtpResendResult contains no recipient data and is safe to return as-is.

Configuration

{
  "Otp": {
    "CodeLength": 6,
    "Expiry": "00:05:00",
    "ResendCooldown": "00:01:00",
    "MaxResendCount": 3,
    "MaxVerifyAttempts": 5,
    "ReferenceIdPrefix": "otp_",
    "HashPepper": "load-this-from-a-secret-store",
    "MockCode": null,
    "UseMockSender": false,
    "ExpiredRecordRetention": "01:00:00",
    "CleanupInterval": "00:15:00",
    "Redis": {
      "ConnectionString": "localhost:6379",
      "KeyPrefix": "otp:",
      "ExpiredRecordRetention": "01:00:00"
    },
    "SqlServer": { "ConnectionString": "...", "Schema": "dbo", "Table": "OtpRecords" },
    "PostgreSql": { "ConnectionString": "...", "Schema": "public", "Table": "otp_records" }
  }
}

Store options are validated too: the SQL stores require ConnectionString and identifier-safe Schema/Table; Redis requires ConnectionString or ConnectionMultiplexer and a non-empty KeyPrefix.

Storage Providers

In-memory is registered by default and is meant for development and tests (single process only):

builder.Services.AddOtp(builder.Configuration);

Redis:

builder.Services
    .AddOtp(builder.Configuration)
    .AddOtpRedis(options => options.ConnectionString = "localhost:6379");

Redis needs no migration. Records live at {KeyPrefix}ref:{referenceId} and the one-active-code slot at {KeyPrefix}recipient:{sha256}; every write is a single Lua script, so it is atomic. For Redis Cluster use a hash-tagged prefix such as {otp}: so both keys share a slot. To reuse an existing connection, set RedisOtpOptions.ConnectionMultiplexer.

SQL Server:

builder.Services
    .AddOtp(builder.Configuration)
    .AddOtpSqlServer(options =>
        options.ConnectionString = builder.Configuration.GetConnectionString("SqlServer")!);

PostgreSQL:

builder.Services
    .AddOtp(builder.Configuration)
    .AddOtpPostgreSql(options =>
        options.ConnectionString = builder.Configuration.GetConnectionString("PostgreSql")!);

Each store registers a health check (otp-redis, otp-sqlserver, otp-postgresql, tagged otp and readiness). The SQL checks also fail when the configured table does not exist, so a missing migration or a wrong Table name is visible.

Initialize the Database

LowCodeHub.OTP does not create or migrate its own schema during service registration; the consuming application owns when the scripts run. This section only applies to .AddOtpSqlServer(...) and .AddOtpPostgreSql(...).

The embedded scripts are idempotent and create the table and indexes with the default names only ([dbo].[OtpRecords], "public"."otp_records"):

Custom schema or table name

If you change Schema/Table, render the script for your names instead of using the embedded resources directly:

string sqlServer = SqlOtp.GetSqlServerSchemaScript(schema: "auth", table: "OtpCodes");
string postgres  = SqlOtp.GetPostgreSqlSchemaScript(schema: "auth", table: "otp_codes");

Run it from your own migration (EF migrationBuilder.Sql(...), DbUp, a deployment script, ...). Index and key names are derived from the table name.

With LowCodeHub.Migration.SqlServer

using LowCodeHub.Migration.SqlServer.Extensions;
using LowCodeHub.OTP.Migrations;

builder.Services.AddSqlServerMigrations(migrations =>
{
    migrations.AddTarget<IOtpScriptScanner>(o =>
    {
        o.ConnectionString = builder.Configuration.GetConnectionString("Otp")!;
        o.Directories = ["LowCodeHub.OTP.Repositories.SqlServer.Scripts."];
    });
});

await app.RunSqlServerMigrationAsync();

With LowCodeHub.Migration.PostgreSql

using LowCodeHub.Migration.PostgreSql.Extensions;
using LowCodeHub.OTP.Migrations;

builder.Services.AddPostgreSqlMigrations(migrations =>
{
    migrations.AddTarget<IOtpScriptScanner>(o =>
    {
        o.ConnectionString = builder.Configuration.GetConnectionString("Otp")!;
        o.Directories = ["LowCodeHub.OTP.Repositories.PostgreSql.Scripts."];
    });
});

await app.RunPostgreSqlMigrationAsync();

Do not scan the whole LowCodeHub.OTP assembly without a directory filter, because the package contains scripts for both providers.

With EF Core Migrations

EF Core does not discover these scripts. Create an application-owned migration and execute them in Up:

using LowCodeHub.OTP.Migrations;
using Microsoft.EntityFrameworkCore.Migrations;

public partial class AddLowCodeHubOtpSchema : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        foreach (var resource in SqlOtp.SqlServerResources)
            migrationBuilder.Sql(SqlOtp.ReadFromResource(resource));

        // or, for custom names: migrationBuilder.Sql(SqlOtp.GetSqlServerSchemaScript("auth", "OtpCodes"));
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
    }
}

For PostgreSQL use SqlOtp.PostgreSqlResources / SqlOtp.GetPostgreSqlSchemaScript(...). SqlOtp.ReadFromResource(...) strips SQL Server GO separator lines.

Delivery Boundary

LowCodeHub.OTP does not depend on Twilio, SendGrid, SMTP, WhatsApp, or any other delivery provider. Register your IOtpSender with AddOtpSender<T>() (scoped). Until one is registered, SendAsync fails with a clear "No IOtpSender is registered" error.

Mock Mode

For local development or automated tests, force a fixed code and use a no-op sender:

builder.Services.AddOtp(options =>
{
    options.HashPepper = "development-only-pepper";
    options.CodeLength = 4;
    options.MockCode = "1234";
    options.UseMockSender = true;
});

MockCode must be numeric and match CodeLength. When MockCode or UseMockSender is set, a warning is logged at startup so a leftover mock configuration cannot reach production silently.

Expired Record Cleanup

A background service deletes expired records once they are older than Otp:ExpiredRecordRetention (so callers still get Expired rather than NotFound shortly after expiry). It runs every Otp:CleanupInterval; set it to 00:00:00 to disable it. The Redis store uses native key TTLs (Otp:Redis:ExpiredRecordRetention) instead.

Metrics

Counters on the LowCodeHub.OTP meter (OtpMetrics.MeterName), tagged otp.channel, otp.purpose, otp.outcome:

builder.Services.AddOpenTelemetry().WithMetrics(m => m.AddMeter(OtpMetrics.MeterName));

Recipients are never recorded. Failed verifications are tagged unknown for channel and purpose.

Security Notes

• Codes are generated with a cryptographically secure RNG and are uniformly distributed.
• Plaintext codes are only passed to IOtpSender; they are never stored. Never log OtpDeliveryMessage.Code.
• Stored codes are HMAC-SHA256(key: HashPepper, salt || code) with a random 32-byte salt per code. Key stretching (PBKDF2/bcrypt) is deliberately not used: a 6-digit code has ~20 bits of entropy, so stretching cannot protect it once the pepper leaks, but it would let anyone burn server CPU through the unauthenticated verify endpoint. Protection comes from the secret pepper, the short expiry and the attempt limits.
• Rotating HashPepper invalidates all outstanding codes (they fail as InvalidCode).
• Verification uses constant-time comparison and hashes at most once per code, even across optimistic-concurrency retries.
• A successful verification consumes the challenge and prevents replay.
• Resend rotates the code, extends expiry and resets failed attempts, so the guess budget per recipient per expiry window is MaxVerifyAttempts × (MaxResendCount + 1) (20 by default). Tune both limits together.
• Recipients are trimmed and lower-cased before storage and matching, so User@example.com and user@example.com are the same recipient on every store.
• Every store enforces "one active code per recipient/channel/purpose" atomically (SQL filtered/partial unique index, Redis Lua script, in-memory slot map), so concurrent SendAsync calls for the same recipient produce exactly one code and the rest get OtpSendThrottledException. This only limits per-recipient abuse — still put a rate limiter (per IP / per account) in front of public OTP endpoints.
• If IOtpSender throws during SendAsync, the new record is deleted so the recipient is not locked out. If it throws during ResendAsync, the previous code is restored (a lost race is logged as a warning).