Authentication¶

The Supabase Auth module implements IUserContext using GoTrue, Supabase's authentication service. It resolves the current user by calling the GoTrue /user endpoint with the bearer token from the incoming HTTP request.

Effects Module¶

The pre-built AuthModule wraps IUserContext as an effect. Include it in your module:

[EffectsModule(typeof(AuthModule))]
[EffectsModule(typeof(StorageModule))]
public partial class AppModule;

In development, AuthModule registers a StubUserContext that returns a fixed test user. In production, AddSupabaseAuth() replaces it with GoTrue-backed authentication:

// Production — Supabase GoTrue
options.AddSupabaseAuth();

// Alternative — Deepstaging JWT + Google OAuth
services.AddDeepstagingAuth(jwt => ..., google => ...);

Overview¶

services.AddDeepstaging(options => options
    .AddSupabaseAuth());

This registers:

• ISupabaseTokenAccessor → HttpContextTokenAccessor — extracts the Authorization: Bearer {token} header
• IUserContext → SupabaseUserContext — calls GoTrue to resolve the user

How It Works¶

Client Request
  │
  ├─ Authorization: Bearer <supabase-jwt>
  │
  ▼
HttpContextTokenAccessor
  │  extracts JWT from header
  ▼
SupabaseUserContext
  │  calls GET /auth/v1/user
  ▼
GoTrue validates token
  │  returns user profile
  ▼
UserClaims(UserId, Email, Name)

The token is validated server-side by GoTrue on every request. This means:

• Banned or deleted users are immediately rejected
• No local JWT validation or key management needed
• Token refresh is handled by the Supabase client SDK

Usage¶

Inject IUserContext anywhere in your application:

public class OrderHandler(IUserContext userContext)
{
    public async Task<Order> Handle(CreateOrderCommand cmd)
    {
        var user = await userContext.GetCurrentUser();
        return new Order(user.UserId, cmd.Items);
    }
}

For optional authentication:

var user = await userContext.GetCurrentUserOrNull();
if (user is null)
    return Results.Unauthorized();

Token Accessor¶

The default HttpContextTokenAccessor extracts the bearer token from HttpContext.Request.Headers.Authorization. For non-HTTP scenarios (background jobs, WebSocket handlers), implement ISupabaseTokenAccessor:

public sealed class CustomTokenAccessor : ISupabaseTokenAccessor
{
    public string? GetAccessToken() => /* your token source */;
}

// Register before AddSupabaseAuth()
services.AddSingleton<ISupabaseTokenAccessor, CustomTokenAccessor>();

GoTrue Client¶

The underlying SupabaseAuthClient is a generated HTTP Client that exposes the full GoTrue API:

Inject SupabaseAuthClient directly when you need operations beyond IUserContext.

ISupabaseAuth Effects¶

For effects-based access to GoTrue operations, use SupabaseAuthModule. This wraps the full auth API as composable effects:

[EffectsModule(typeof(SupabaseAuthModule))]
public partial class AppModule;

Register the implementation:

options.AddSupabaseAuthOperations();

Then compose auth operations inside your effect pipelines:

public static Eff<AppRuntime, Unit> InviteAndNotify(string email) =>
    from session in AppEffects.SupabaseAuth.SignUpAsync<AppRuntime>(email, GeneratePassword())
    from _       in AppEffects.Notify.SendAsync<AppRuntime>(new UserInvited(email))
    select unit;

Available Operations¶

Row Level Security¶

Supabase Auth pairs with Row Level Security (RLS) for defense-in-depth. RLS policies run inside Postgres and enforce access rules regardless of which application code queries the data:

-- Users can only see their own orders
CREATE POLICY "Users see own orders" ON orders
  FOR SELECT
  USING (auth.uid() = user_id);

This complements application-level authorization (Dispatch Authorization) — even if a bug bypasses your application checks, the database rejects unauthorized access.