Omni2FA.Core 0.7.2

Omni2FA

Drop-in multi-method two-factor authentication for self-hosted apps — TOTP, Email OTP, WebAuthn/passkeys, recovery codes — behind one OpenAPI contract.

You verify the password and mint your session; Omni2FA handles everything 2FA in between — enrollment, the login challenge, OTP/WebAuthn ceremonies, recovery codes, persistence, rate limiting, audit. Backend service + endpoints + EF store on .NET; headless hooks on React. Other stacks implement the same contract (roadmap below).

For apps that own their user table (ASP.NET Core Identity, custom JWT/cookie auth, …). Not for managed identity providers (Auth0, Clerk, Cognito, Firebase, Supabase, Okta, WorkOS) — they already ship 2FA.

Packages

Other backends (Node, Python) and frontends (Angular, Vue) are on the roadmap; any stack can implement the OpenAPI contract.

Backend — ASP.NET Core

dotnet add package Omni2FA.AspNetCore
dotnet add package Omni2FA.AspNetCore.EntityFrameworkCore

Program.cs

builder.Services.AddOmni2Fa(o => builder.Configuration.GetSection("Omni2Fa").Bind(o));
builder.Services.AddOmni2FaEntityFrameworkStore<AppDbContext>();   // or implement the store interfaces yourself

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapOmni2Fa();                                                  // mounts /api/2fa/*

Your DbContext

protected override void OnModelCreating(ModelBuilder modelBuilder) {
    base.OnModelCreating(modelBuilder);
    modelBuilder.ApplyOmni2FaConfiguration();                      // 2FA tables (names configurable)
}

Hook the pre-auth token into your existing login — the seam between your password check and the 2FA step:

public class AuthService(IPreAuthTokenIssuer preAuth, ITwoFactorMethodStore methods) {
    // after you verify the password:
    if (await methods.HasActiveMethodsAsync(userId)) {
        var ticket = preAuth.Issue(userId);                        // short-lived JWT
        var available = await methods.ListActiveByUserAsync(userId);
        return Challenge(ticket.Token, ticket.ExpiresAt, available); // your DTO → frontend
    }
    // else: mint your session as usual

    // when the frontend finishes 2FA, it calls your "finalize" with the verifiedToken from the verify response:
    var verifiedUserId = preAuth.ValidateVerified(verifiedToken);  // null if not actually verified → reject
}

Use the DTOs the library already ships at the host seam — don't reinvent them (all in Omni2FA.Core.Dtos / .Services):

appsettings.json

"Omni2Fa": {
  "PreAuth":  { "SigningKey": "<32+ char HMAC key — from env/secrets>" },
  "Totp":     { "Issuer": "MyApp" },
  "Email":    { "FromAddress": "no-reply@myapp.com",
                "Smtp": { "Host": "smtp.example.com", "Port": 587, "Username": "...", "Password": "...", "UseStartTls": true } },
  "WebAuthn": { "RelyingPartyId": "myapp.com", "Origins": [ "https://myapp.com" ] }
}

That's the whole backend: endpoints, the three methods, recovery codes, rate limiting and audit are live.

Frontend — React

npm i @omni2fa/core @omni2fa/react

Once, at the app root

import { createOmni2Fa } from '@omni2fa/core';
import { Omni2FaProvider } from '@omni2fa/react';

export const omni = createOmni2Fa({ baseUrl: '/api/2fa' });
// after your login, hand the client your host session token (or use cookies: createOmni2Fa({ credentials: 'include' })):
omni.client.setSessionToken(sessionToken);

<Omni2FaProvider value={omni}>{children}</Omni2FaProvider>

The hooks expose state + actions; you render the UI (headless).

Login challenge

import { useChallenge } from '@omni2fa/react';

const { status, context, pick, submit, useRecoveryCode } = useChallenge();
// pick(methodId) → submit(code)  (WebAuthn auto-runs the browser ceremony)
// status: 'idle' | 'awaitingCode' | 'asserting' | 'verifying' | 'verified' | 'failed' | …
// on 'verified': send context.verifiedToken to your finalize endpoint (not the pre-auth token)

Hooks: useMethods, useTotpEnrollment, useEmailEnrollment, useWebAuthnEnrollment, useChallenge (+ *Selector variants). A full headless UI you can copy lives in examples/full/frontend. Styled drop-in components (@omni2fa/react-mui) are planned.

Configuration (key options, under Omni2Fa)

Extension points (swap any piece — TryAdd, host wins)

Methods & status

🚧 Status — pre-1.0 (0.6.x). Functionally complete for .NET + React, verified by a live end-to-end run, but young: no automated test suite yet (planned for v1.0), and WebAuthn/email not yet battle-tested across many environments. Suitable for your own apps; harden before betting a production product on it.

More

• examples/full — runnable ASP.NET + React + SQLite app with all methods.
• docs/ARCHITECTURE.md · docs/FLOWS.md · docs/ROADMAP.md · docs/PUBLISHING.md
• Core/protocol/omni2fa.openapi.yaml — the cross-stack contract.

License

MIT — see LICENSE.