.NET · Winche Stack

Winche.Console

v3.2.0

An embeddable admin console for Winche.Database and Winche.Storage. Browse and edit JSON documents, manage stored files, and edit access rules through a web UI with its own authentication and roles.

View on NuGet → Source on GitHub ↗ ← All packages

Install

dotnet add package Winche.Console

An in-process admin console (superuser data + storage browser) for a .NET app that already uses Winche.Database and Winche.Storage. It ships as a NuGet library you drop into your own ASP.NET Core app — there is no separate service to deploy.

It is the Firebase-console-style view over your app's single datastore: browse, query, and edit JSON documents through a Firestore-style collapsible field tree (every map and array collapses, edits are inline and persist on confirm); and upload, download, browse, edit metadata on, and delete stored files — create folders (kept in memory until you upload the first file) or delete a whole folder and everything under it (cascading) — with each file's upload status (pending / complete / failed) shown inline. Destructive deletes (documents, collections, files, folders) always ask for confirmation first. It manages its own accounts and roles (built-in authentication), and — when you opt in — provides a GUI editor for your Firestore-style security rules with live hot-swap and versioned history (see Rule editor below). Indexes and triggers are not managed here — those live in your app's C# startup (UseIndexes / UseHooks).

Use it

In the ASP.NET Core app that already registers the Winche cores:

builder.Services.AddWincheDatabase(cfg => cfg.ConnectionString = conn);
builder.Services.AddWincheStorage(opts => opts.ConnectionString = conn);
builder.Services.AddWincheConsole(o =>
{
    o.ConnectionString = consoleAuthConn;   // the console's own auth database (Identity tables)
    o.SeedAdminEmail = "[email protected]"; // optional: seeds a first admin on first run
    o.SeedAdminPassword = "…";

    o.AddDatabaseTab();                     // opt in to the document browser (needs AddWincheDatabase)
    o.AddStorageTab();                      // opt in to the file browser (needs AddWincheStorage)
});

var app = builder.Build();
app.MapWincheConsole("/_console");          // JSON API + embedded SPA under this prefix; self-protected
app.Run();

Open /_console. The console resolves the data source that AddWincheDatabase / AddWincheStorage already register (keyed internally), and browses via the unguarded cores (DocumentDatabase / FileStorage), so rules are bypassed exactly like the Firebase console's superuser view. Choose any prefix you like (/_console is the default); the SPA discovers it at runtime via an injected <base href>.

The Database and Storage tabs are opt-in — call AddDatabaseTab() / AddStorageTab() for the ones you want (a Database-only app simply omits AddStorageTab() and never shows a Storage tab or maps its endpoints). Each takes an optional builder for a minimum role and its rules editor — o.AddDatabaseTab(b => { b.MinRole = ConsoleRole.Member; b.UseRulesEditor(); }). MinRole is the floor to see and read the tab (writes still require at least Member); the default is Viewer. Calling AddDatabaseTab() without AddWincheDatabase() (or AddStorageTab() without AddWincheStorage()) throws a clear startup error. The Access tab (user management) stays automatic — it's the console's own auth, shown to Admins in Identity mode.

Authentication & roles

The console is its own auth realm — built on EF Core + ASP.NET Core Identity, stored in a separate database you point it at (ConsoleOptions.ConnectionString). It uses a named cookie scheme scoped to its own endpoints, so it does not touch your host app's auth. You do not call RequireAuthorization.

Using Keycloak instead of built-in Identity

Instead of the built-in Identity database, the console can delegate all authentication to an existing Keycloak realm. In this mode it holds no user database — Keycloak owns login, MFA, password reset, and user/role management.

Configure it explicitly in code via UseKeycloak — Server, Realm, and ClientId are required (the console reads no IConfiguration section of its own):

builder.Services.AddWincheConsole(o => o.UseKeycloak(k =>
{
    k.Server   = "https://id.example.com"; // required
    k.Realm    = "myrealm";                 // required
    k.ClientId = "winche-console";          // required — the console's dedicated Keycloak client
    k.AdminRole  = "Admin";                 // Keycloak role names → console roles (defaults shown)
    k.MemberRole = "Member";
    k.ViewerRole = "Viewer";
    // k.ClientSecret = "...";              // only if the console client is confidential
    // k.RequireHttpsMetadata = false;      // only for a local/dev Keycloak served over http
    // k.AuthPolicyScheme = "WincheConsoleKeycloak"; // name of the console's bearer scheme (default shown)
}));

If your app keeps these in configuration, read them yourself and pass them in (see the sample's Program.cs). The console uses its own dedicated Keycloak client and an isolated bearer scheme — it never touches or depends on a Winche.KeycloakClient registration your app may already have.

In your realm:

  1. Create one dedicated client for the console (separate from your app's own client) with the console callback URL (e.g. https://yourapp/_console/auth/callback) in Valid Redirect URIs and the origin in Web Origins. A public client (PKCE) is sufficient; set ClientSecret only if you make it confidential.
  2. Add an Audience protocol mapper on that client so access tokens include it in aud — the console validates that incoming JWTs are audienced for its own ClientId (see below) and rejects tokens that aren't.
  3. Define realm roles Admin / Member / Viewer (or your mapped names) and assign them to users. Keep each user's realm default roles (e.g. default-roles-<realm>) so they retain the account permissions needed for the in-console "Manage account" link.

Token validation. Each request is validated by the console's own isolated bearer scheme: aud must contain ClientId, the issuer must match {Server}/realms/{Realm}, and the signature is checked against the realm JWKS. This is independent of any Winche.KeycloakClient registration your app already has — a token minted for your app's client will not pass the console's scheme, and vice-versa.

Scheme name (AuthPolicyScheme). The console registers its bearer scheme under the name WincheConsoleKeycloak by default; set AuthPolicyScheme to change it. Because your host's own UseAuthentication runs its default scheme on every request, a console-audience token reaching the host's Bearer handler fails audience validation and logs noise (IDX10214). The clean fix is a path-based forwarder on the host so console requests authenticate with the console's scheme — and AuthPolicyScheme gives you a stable name to target:

builder.Services.AddAuthentication()
    .AddPolicyScheme("Smart", "Smart", o => o.ForwardDefaultSelector = ctx =>
        ctx.Request.Path.StartsWithSegments("/_console")
            ? "WincheConsoleKeycloak"                   // == AuthPolicyScheme
            : JwtBearerDefaults.AuthenticationScheme);  // your host's "Bearer"
builder.Services.PostConfigure<AuthenticationOptions>(o => o.DefaultScheme = "Smart");

Account management. In Keycloak mode the profile menu (bottom of the nav) shows Manage account, which opens Keycloak's account console for the signed-in user. Login, password, MFA, and profile are all owned by Keycloak. ConnectionString, SeedAdmin*, invites, 2FA, and the in-console user-management screens do not apply in Keycloak mode.

Rule editor (optional)

Call b.UseRulesEditor() on a built-in tab and the console adds a Rules sub-tab to that screen for editing the Firestore-style security rules that guard Winche.Database and Winche.Storage (the Winche.Rules engine). Edits hot-swap into the live engine immediately — no restart — and every save is a durable, versioned entry you can review and revert to.

services.AddWincheConsole(o =>
{
    o.ConnectionString = consoleConn;                       // REQUIRED once any rule editor is enabled
    o.AddDatabaseTab(b => b.UseRulesEditor());              // Database tab + its Rules sub-tab
    o.AddStorageTab(b => b.UseRulesEditor(r => r.ApplyPersistedRulesOnStartup = false)); // Storage tab + Rules
});

Custom tabs (server-driven dashboards)

Register a tab as a declarative layout tree in C#; the console renders it. Widget data comes from typed handler methods on DI-resolved provider classes, bound by selector. Filters are nodes that scope a value to their subtree and either re-fetch it or switch which widgets show.

o.AddTab("analytics", "Analytics", tab =>
{
    tab.Icon = "chart-bar";
    tab.MinRole = ConsoleRole.Member;
    tab.Layout(new Filter(new Select("range", ["7 days", "30 days"]),
    [
        new StatRow<AnalyticsData>(d => d.Kpis),
        new Row([ new Chart<AnalyticsData>(d => d.Signups, ChartKind.Line) { Flex = 2 },
                  new Table<BillingData>(d => d.Invoices) { Flex = 1 } ]),   // mix providers in one tab
    ]));
});

public sealed class AnalyticsData(IAnalytics analytics)   // constructor-injected, resolved per request
{
    public async Task<StatRowData> Kpis(WidgetContext ctx, CancellationToken ct)
        => new(new Stat("Users", await analytics.CountAsync(ctx.Inputs["range"], ct), "+12%", Trend.Up));
    public Task<ChartData> Signups(WidgetContext ctx, CancellationToken ct) => /* … */;
}

Interactivity: search, refresh, pagination, commands

The tree also carries a bounded set of interactive primitives. Each maps to a named server capability, so tabs feel live without the declarative model turning into a client-side UI framework:

var create = tab.Command((UsersTab d) => d.CreateUser, c => { c.Label = "Create user"; c.MinRole = ConsoleRole.Admin; });
var delete = tab.Command((UsersTab d) => d.DeleteUser, c => { c.Label = "Delete"; c.MinRole = ConsoleRole.Admin; c.Confirm = "Delete this user?"; });
tab.Layout(new Filter(new TextInput("q") { Placeholder = "Search email…", Apply = Apply.Manual },
[
    new Row([ new Button(create), Button.Refresh("Refresh") ]),
    new Table<UsersTab>(d => d.Rows) { Paginate = 20, RowActions = [ new RowActionRef(delete) ] },
]));

public sealed record CreateUserInput(
    [property: Display(Name = "Email"), Required, EmailAddress] string Email,
    [property: Required] UserRole Role,                        // enum → Select
    [property: Display(Name = "Active")] bool Active = true);  // bool → switch

public sealed class UsersTab
{
    public WidgetHandler<TableData> Rows => (ctx, ct) => /* filter by ctx.Inputs["q"], slice via ctx.Page("rows", 20) */;
    public CommandHandler<CreateUserInput> CreateUser => (ctx, ct) =>           // typed form input
        Task.FromResult(Exists(ctx.Input.Email)
            ? CommandResult.Invalid(nameof(CreateUserInput.Email), "Already taken")   // inline field error
            : CommandResult.Ok($"Created {ctx.Input.Email}"));
    public CommandHandler DeleteUser => (ctx, ct) =>                            // row key, no form
        Task.FromResult(CommandResult.Ok($"Deleted {ctx.RowKey}"));
}

Escape hatch: embed a custom island

When a tab needs interactivity beyond these bounded primitives — arbitrary local state, a bespoke editor, or a non-C# UI — add an Embed node: the console mounts a consumer-authored document in a same-origin <iframe> at that spot in the layout. The declarative tree handles the common cases above; the island owns everything else, rendering its own UI and fetching its own endpoints.

new Column([
    new StatRow<AnalyticsData>(d => d.Kpis),
    new Embed("collections-editor", "/plugins/collections-editor") { Flex = 1, MinHeight = 320 },
])

The console bridges a closed postMessage protocol: on load it sends winche:init (current user + theme, and in Keycloak mode a bearer token) and, on silent renewal, winche:token; the island may send back exactly winche:resize, winche:refetch (reload the sibling declarative widgets), and winche:notify (raise a console toast). Messages are origin- and source-pinned both ways.

samples/flutter-demo is a runnable Flutter web island that exercises the whole protocol end to end (inbound init/token; outbound resize/refetch/notify, incl. a Flutter button reloading a sibling declarative widget) — see its README for the one build command.

API (under the chosen prefix)

Document/file paths are standard-base64 of the UTF-8 path (those that travel in a route segment); the storage write endpoints take the path in the body/query instead. Malformed base64 returns 400.

File upload/download use presigned URLs. upload-url creates the record and returns a short-lived URL the browser PUTs the bytes to; confirm then finalizes it. download-url returns a short-lived GET URL. This needs an object store (S3/MinIO) configured on Winche.Storage — with a metadata-only archive the records exist but byte transfer is unavailable. Known limitation: the console uses ASP.NET Core Identity's standard cookie scheme names. If your host app also uses ASP.NET Core Identity, the scheme names would collide. Winche consumers typically use their own auth (or BYO-JWT), so this is fine in practice. Collection and storage-folder listing use the library's own listers — ListCollectionIdsAsync (Winche.Database 8.3) and ListDirectoryIdsAsync (Winche.Storage 6.3).

What it is not

Develop

The SPA lives in web/ (React + Vite + TypeScript + Mantine) and builds into src/Winche.Console/wwwroot, where it is embedded into the NuGet package.

Tests

dotnet test boots tests/SampleHost (a minimal app that calls AddWincheConsole) via WebApplicationFactory and exercises auth (setup/login/roles), user management, two-factor (real TOTP), the optional email flows, and the data/storage/SPA behavior. It spins an ephemeral PostgreSQL container with Testcontainers (a separate database for the console's auth tables), so a running Docker daemon is required; no local services or fixed ports are needed.