SuperTokens 1.1.0

SuperTokens .NET SDK (port of supertokens-golang)

A C# / .NET port of the SuperTokens Go backend SDK. Targets .NET 10, idiomatic C# (async/await, nullable reference types, exceptions instead of (value, error) tuples), System.Text.Json, and ASP.NET Core minimal-API / middleware integration (no MVC controllers).

Solution layout

SuperTokens.sln
Directory.Build.props          # shared: net10.0, nullable, implicit usings
CONVENTIONS.md                 # Go → C# porting contract
src/SuperTokens/               # the SDK (one class library, one assembly)
  Core/                        # namespace SuperTokens  — framework core
    Exceptions, Constants, Logger, Json, UserContext, Models,
    NormalisedUrlDomain, NormalisedUrlPath, Utils, Querier,
    RecipeModule, PostInitCallbacks, UserIdMapping,
    SuperTokensInstance, SuperTokensApi
  Ingredients/
    EmailDelivery/             # SuperTokens.Ingredients.EmailDelivery (MailKit/SMTP)
    SmsDelivery/               # SuperTokens.Ingredients.SmsDelivery (Twilio)
  Recipe/
    Jwt, OpenId, Session, Multitenancy, ThirdParty, EmailVerification,
    UserRoles, EmailPassword, Passwordless, UserMetadata, Dashboard
test/SuperTokens.Tests/        # xUnit tests

Unlike Go (where each recipe is a separate package and import cycles are illegal), the entire SDK is one assembly, so recipes may reference each other freely. Namespaces still mirror the Go package tree (SuperTokens.Recipe.<Name>).

Design decisions

• map[string]interface{} → Dictionary<string, object?>. A custom InferredTypesConverter (in Core/Json.cs) makes System.Text.Json deserialize into native CLR types (double / bool / string / Dictionary / List), matching Go's encoding/json semantics.
• Errors → exceptions. SuperTokensException (base) and BadInputException (→ HTTP 400). Functions that returned (T, error) now return T and throw.
• IO is async. The querier uses HttpClient; everything reaching the core is async Task.
• Overridable interfaces. Go's "struct of function pointers + Override" pattern is ported as sealed classes with nullable delegate properties.
• Web layer. Go's net/http middleware/handler model maps to ASP.NET Core HttpContext + RequestDelegate. Register with app.UseSuperTokens().

Usage sketch (minimal API)

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

await SuperTokensApi.Init(new SuperTokensConfig
{
    Supertokens = new ConnectionInfo { ConnectionUri = "http://localhost:3567" },
    AppInfo = new AppInfo
    {
        AppName = "My App",
        ApiDomain = "http://localhost:3001",
        WebsiteDomain = "http://localhost:3000",
    },
    RecipeList = new List<RecipeFactory>
    {
        // Session.Init(), EmailPassword.Init(), ...
    },
});

app.UseSuperTokens();              // dispatches SuperTokens recipe APIs
app.MapGet("/hello", () => "hi");  // your own minimal-API endpoints
app.Run();

Protecting your own endpoints

Don't hand-roll auth checks — wrap an endpoint (or a whole route group) with RequireSession(). It verifies the access token, and on a missing / expired / invalid session it writes the correct response itself (a 401, or a "try refresh token" 401 that tells the frontend to call the refresh endpoint) and skips your handler. Inside a protected handler, read the verified session with Session.GetSessionFromRequestContext(ctx).

using SuperTokens.AspNetCore;            // RequireSession()
using SuperTokens.Recipe.Session;        // Session, VerifySessionOptions
using SuperTokens.Recipe.Session.SessModels;

app.UseSuperTokens();   // must come before your endpoints

// Protected — runs only with a valid session
app.MapGet("/user/profile", (HttpContext ctx) =>
{
    var session = Session.GetSessionFromRequestContext(ctx)!;
    return Results.Ok(new
    {
        userId  = session.GetUserId(),
        payload = session.GetAccessTokenPayload(),
    });
}).RequireSession();

// Optional session — handler still runs when there's no session
app.MapGet("/maybe", (HttpContext ctx) =>
{
    var session = Session.GetSessionFromRequestContext(ctx); // null if not signed in
    return Results.Ok(new { signedIn = session is not null });
}).RequireSession(new VerifySessionOptions { SessionRequired = false });

// Protect a whole group
var secure = app.MapGroup("/api").RequireSession();
secure.MapGet("/orders", (HttpContext ctx) => Results.Ok(/* ... */));

Notes:

• app.UseSuperTokens() must be registered before your endpoints (it wires the /auth/* recipe routes and the shared error handler that turns session failures into proper responses).
• For role/permission checks, pass claim validators via VerifySessionOptions.OverrideGlobalClaimValidators, or read session.GetAccessTokenPayload() and check it yourself.
• Avoid calling Session.GetSession(req, res) directly in a custom endpoint unless you wrap it: with SessionRequired defaulting to true it throws UnauthorisedError / TryRefreshTokenError, and those only become proper HTTP responses when routed through the SuperTokens error handler — which RequireSession() does for you.

Status

Known limitations / gaps

• Public Suffix List. Utils.GetTopLevelDomainForSameSiteResolution uses a last-two-labels heuristic instead of the PSL that Go uses (golang.org/x/net/publicsuffix). Multi-level suffixes (e.g. .co.uk) are not resolved precisely. Consider bundling a PSL library for production.
• Querier GET cache. The per-request core-call cache keyed by params+headers is simplified; cache invalidation hooks exist but the GET read-through cache is not fully reproduced.
• See per-recipe notes for recipe-specific gaps.

Running the tests

# Fast unit tests (no Docker)
dotnet test test/SuperTokens.Tests

# Integration tests — require Docker. Testcontainers starts a real
# supertokens-core backed by a real PostgreSQL (both on a shared network) and the
# SDK runs emailpassword sign-up/sign-in and session create/verify/revoke against it.
dotnet test test/SuperTokens.IntegrationTests

Images (both overridable via env vars):

The core is pinned to a version that advertises CDI 3.1 (the version this SDK targets). Testcontainers' Ryuk cleans up both containers and the network automatically.

Reference source

The original Go source is cloned (git-ignored) at _src_golang/ for reference during the port.