Solhigson.Admin 10.2.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Solhigson.Admin --version 10.2.0
                    
NuGet\Install-Package Solhigson.Admin -Version 10.2.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Solhigson.Admin" Version="10.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Solhigson.Admin" Version="10.2.0" />
                    
Directory.Packages.props
<PackageReference Include="Solhigson.Admin" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Solhigson.Admin --version 10.2.0
                    
#r "nuget: Solhigson.Admin, 10.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Solhigson.Admin@10.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Solhigson.Admin&version=10.2.0
                    
Install as a Cake Addin
#tool nuget:?package=Solhigson.Admin&version=10.2.0
                    
Install as a Cake Tool

Solhigson.Admin

Admin screens for Solhigson apps, built as Razor components and rendered on the server: static server rendering with enhanced navigation, no interactive mode. It builds on Solhigson.Framework.Core.

An app owns its routes. The package ships no page: every component here is placed by the app, on a page the app declares with its own @page route and its own permission.

The head

KitHead (Solhigson.Admin.Components) links the kit's stylesheets, kit.css first, through Assets[...], so a host that calls app.MapStaticAssets() serves each at its content-specific url. Place it in the app's <head>, before the app's own stylesheets:

<head>
    <KitHead Nonce="@nonce" />
    <link rel="stylesheet" href="@Assets["app.css"]" />
</head>

Nonce is optional. An app whose Content-Security-Policy allows styles or scripts by nonce passes the nonce it generated for this response's CSP header, fresh for each response, never a value read from the request; KitHead puts it on every link and script it emits.

After its stylesheets, KitHead loads the kit's scripts with defer: kit.forms.js, the busy mark under Buttons; kit.theme.js, the switch under Light and dark; kit.dialog.js, which opens and fills the dialogs under Dialogs and confirms; and kit.menu.js, which places the row menus under Row menus.

Tokens

kit.tokens.css states every colour, size, space, radius, shadow, duration and font the kit reads, as --kit-* custom properties on :root; no other kit stylesheet holds a value of its own. The kit's one colour is black: the ink is #000000 and every grey is untinted; the four states (success, warn, danger, info) are its only hues.

Each colour and shadow has a dark value. A page follows the reader's prefers-color-scheme unless it sets data-theme="light" or data-theme="dark" on its <html> element. Every text and state colour meets WCAG contrast 4.5 to 1 on the surfaces it sits on, and the control border and focus ring 3 to 1, in both themes.

The fonts are the reader's system faces; the package ships no font file and links no font host. An app that wants other faces sets --kit-font-sans, --kit-font-serif and --kit-font-mono.

Overriding the kit

kit.css, the first stylesheet KitHead links, names the cascade layers, lowest first: @layer reset, kit.tokens, kit.base, kit.components, app;. KitHead goes before the app's stylesheets, since layer order is set where a layer is first seen. A rule in a later layer beats one in an earlier layer whatever its specificity, so an override in app needs no !important; no kit rule uses !important or an id selector.

An app overrides the kit at three levels, each in its own @layer app:

  1. A global token, such as --kit-ink, set on :root. A token override gives its own dark value, in the two blocks the kit uses: under @media (prefers-color-scheme: dark) on :root:not([data-theme="light"]), and on :root[data-theme="dark"]. Without them your light value stays in dark mode, on the kit's dark surfaces: a layer beats the kit whatever its selector. An app overriding --kit-ink sets --kit-on-ink, the text on it, beside it in each theme, and --kit-ink-hover, a primary button's fill under the pointer; one overriding --kit-state-danger sets --kit-state-danger-hover likewise. The focus ring is black (white in dark) and stays so: an app re-inking the kit decides --kit-focus itself.
  2. A component token, such as --kit-mark-gap or --kit-btn-height, which a component reads before its global fallback (var(--kit-mark-gap, var(--kit-sp-1))). The kit sets no component token; an app sets it, on :root or on the component.
  3. A rule of the app's own that selects a kit class, such as .kit-mark-version.
@layer app {
    :root { --kit-ink: #143f2a; --kit-on-ink: #ffffff; --kit-mark-gap: var(--kit-sp-2); }
    @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --kit-ink: #7fc8a2; --kit-on-ink: #000000; } }
    :root[data-theme="dark"] { --kit-ink: #7fc8a2; --kit-on-ink: #000000; }
    .kit-mark-version { color: var(--kit-fg-muted); }
}

A kit component is a name kit.manifest.json declares in its components, with its classes. Its parts keep single hyphens (.kit-mark-name): a class belongs to the longest declared component it starts with, so .kit-mark-name is kit-mark's, and a component's tokens are named --<component>-*, so --kit-mark-gap is kit-mark's. A new component is declared by adding its name to the manifest's components, a name that is a kit class some kit rule selects (kit-mark for .kit-mark); the manifest's regeneration test then fills in its classes.

An app's reset goes in the reset layer, below the kit's, so the kit's rules still apply over it. An unlayered rule beats every layer, so a legacy unlayered stylesheet on the same page (Bootstrap) overrides the kit. Import it into a layer the kit names instead, after KitHead: @import url("bootstrap.css") layer(reset);. A layer name kit.css does not declare lands above app, so a legacy stylesheet in a layer of its own would still beat the app's overrides.

kit.manifest.json, served at _content/Solhigson.Admin/kit.manifest.json, names every global token, component token, component and class the kit offers. A name leaving the manifest is a breaking change: an app's override of it stops applying, with no error.

Motion

Every motion the kit makes reads a duration token, --kit-d-1 (a hover), --kit-d-2 (an opening) or --kit-d-3 (a larger move). Every kit motion that takes time names its curve, a curve token, --kit-ease, --kit-ease-leave and --kit-ease-theme (something arriving or moving, something leaving, a theme's colours changing), or linear, a steady turn such as the busy ring's. Under prefers-reduced-motion: reduce every --kit-d-* token is 0ms and scroll-behavior is auto, so a viewer who asks for less motion sees none. A dwell token, named --kit-<component>-dwell, is a wait, not a motion: it keeps its time, so a confirmation still leaves after it.

A motion an app adds in @layer app reads a --kit-d-* token, so reduced motion stops it too; a component duration token of its own falls back to one (var(--app-panel-d, var(--kit-d-2))). An app that sets a duration token of its own repeats it as 0ms under prefers-reduced-motion too, since its value wins over the fallback. An app that overrides a --kit-d-* token repeats it as 0ms under prefers-reduced-motion, as a colour override gives its own dark value: the app's layer wins over the kit's reduced-motion block.

@layer app {
    :root { --kit-d-2: 160ms; }

    @media (prefers-reduced-motion: reduce) {
        :root { --kit-d-2: 0ms; }
    }
}

Buttons

KitButton renders a <button>, type="button" unless Type says otherwise, so a button inside a form submits it only when asked to. Variant is Default, Primary (the screen's one solid black element), Danger (the danger fill, for an action that cannot be undone) or Ghost (no fill or edge until hovered, for a toolbar or a row).

<KitButton Variant="KitButtonVariant.Primary" Type="submit">Save</KitButton>
<KitButton Href="~/users" class="app-wide">Users</KitButton>
<KitButton Href="~/users" Disabled>Users</KitButton>

With Href, it is a link, <a class="kit-btn">, to the address KitHref.LocalOrHttps makes of it (see Links). A refused Href, or Disabled on a link, renders <span aria-disabled="true">, which goes nowhere. Every other attribute passes through, and a class joins the kit's; a url attribute (formaction, ping, src and the like) is refused with an exception, since it would reach the page past KitHref.

Every variant is one control height tall: --kit-btn-height, falling back to --kit-control-h.

kit.forms.js marks the kit button that submits a form aria-busy="true" until the answer is on the page: Blazor's enhancedload for an enhanced form, pageshow for a full load. A busy button keeps its width: its label turns transparent in place and a ring turns at its centre. A submit some script cancels marks nothing, unless the form is enhanced (data-enhance): Blazor cancels that submit to post the form itself. A dialog form, or one aimed at another window, marks nothing either.

Status pills and alerts

KitStatusPill says a status in a word: Tone (Neutral, Success, Warn, Danger or Info) sets its colour, and Text, which it requires, says it, since a status is never colour alone.

KitAlert is a message about the page in the same tones, with an optional Title and its body as child content, its lines no wider than --kit-measure. A Neutral, Success or Info alert has role="status", which a screen reader reads when it is next idle; a Warn or Danger alert has role="alert", which it reads at once.

<KitStatusPill Tone="KitTone.Success" Text="Active" />
<KitAlert Tone="KitTone.Danger" Title="Not saved"><p>The email is taken.</p></KitAlert>

Form fields

KitField renders one labelled control with its hint and its error. Kind is Text, Email, Password, Number, Date, Search, Textarea, Select, Checkbox or Toggle; Name and Label are required.

<KitField Name="Email" Label="Email" Kind="KitFieldKind.Email" Value="@model.Email" Required
          Hint="We send the sign-in link here." Error="@errors.GetValueOrDefault("Email")" />
<KitField Name="Role" Label="Role" Kind="KitFieldKind.Select" Value="@model.Role" Placeholder="Choose a role"
          Options="@([("operator", "Operator"), ("approver", "Approver")])" />
<KitField Name="Notify" Label="Email me on changes" Kind="KitFieldKind.Toggle" Value="@model.Notify.ToString()" />
  • The <label> names the control by for and id; the hint and the error describe it by aria-describedby.
  • An Error marks the control aria-invalid="true" and shows its text after a glyph whose text alternative is the word "Error", so it is not colour alone. Static rendering posts a plain form, so the error text comes from the server; the field shows what it is given.
  • Required puts required on the control and a visible mark in the label, read as "(required)".
  • The id is kit-field- and the Name, every character that is not an ASCII letter or digit written as _ and its four hex digits (Items[0].Name is kit-field-Items_005B0_005D_002EName). It is the same on every render and different for every other name. Two fields of one Name on one page, in two forms, each need their own Id.
  • A Password never writes Value into the page, so a stored secret shows only as set or not set; it carries autocomplete="new-password" unless AutoComplete says otherwise, since browsers ignore off on a password and would fill the administrator's own saved password.
  • A Select takes its Options as value and text pairs, in order; the option whose value equals Value, compared ordinally, is selected. Placeholder adds a first, empty option, chosen when Value is empty.
  • Min, Max and Step are a Number's or a Date's; ReadOnly is an input's or a textarea's, since a browser lets a select, a checkbox and a toggle change though they are read-only (use Disabled). A parameter the kind cannot honour is refused with an exception, as are Options on any kind but a Select.
  • Every other attribute lands on the control. The field owns id, name, required, disabled and aria-invalid on every control; type, value, placeholder, min, max, step, readonly and autocomplete on an input; placeholder, readonly and autocomplete on a textarea; autocomplete on a select; type, value and checked on a box or a toggle; and role on a toggle. It writes them after the caller's, so a passed one is replaced; set them through the parameters. A passed class and a passed aria-describedby join the field's own. A url attribute is refused, as KitButton refuses it.
  • An input and a select are one field height tall: --kit-field-height, falling back to --kit-control-h.

A Checkbox or a Toggle posts value="true" when ticked and nothing at all when not: there is no hidden field. It is ticked when Value is true in any case, so Value="@model.Notify.ToString()" works. A handler reads an absent box as false by binding it to a bool, which the absent field leaves false: [SupplyParameterFromForm] public bool Notify { get; set; } in a component, or a bool property of an MVC model. A Toggle is the same checkbox with role="switch", drawn as a track and a thumb, so it never looks like a box to tick.

A disabled field, like an unticked box, posts nothing, and a viewer can post any field the page never showed them. So a handler writes only the fields the signed-in viewer may change, decided by their permission on the server, never by which fields arrived or which the page disabled, and leaves every other value as stored.

Setting fields

KitSettingField shows one declared setting as a row of a settings list: its label and purpose, one control of its kind (KitSetting.From makes its Setting from the framework's DeclaredSettingLine), the hint with its bounds and default, where its value comes from, and a pill and a sentence for each flag. A Secret, a row stored sensitive and a value shown as the mask are a password field that starts empty; nothing of the value is written into the page. With ReadOnly, or on a line that cannot be edited, the row shows its value as text, "Hidden" for one that may not be shown.

KitSettingField renders no form of its own: the screen places each setting in a form of its own, with its Save button. Its controls post the bare names Value, Amount and Unit (a duration as an amount posts Amount and Unit; every other kind posts Value), so the screen binds them with [SupplyParameterFromForm(Name = "")] and turns them into the setting's text with KitSettingValue.Compose:

<form method="post" @formname="setting" @onsubmit="Save">
    <AntiforgeryToken />
    <KitSettingField Setting="@setting" Fields="@Posted" Error="@error" />
</form>

@code {
    [SupplyParameterFromForm(FormName = "setting", Name = "")]
    private KitSettingFields? Posted { get; set; }

    private void Save() => composed = KitSettingValue.Compose(setting, Posted);
}

An unticked toggle posts nothing, so Value binds null, which KitSettingValue.Compose reads as false; when the toggle is the form's only field the whole KitSettingFields binds null, which Compose reads the same way. A line shown as the mask is the exception: controls left empty compose to the mask, which the framework's save reads as no change.

ChildContent, when given, is placed last in the row, in the control's column under the hint, the error and the lines, in a box of its own (kit-setting-actions) that stacks what it holds a section step apart. The settings screen puts its buttons and what a post came to there, so they sit inside the row they act on; with none given, no box is drawn.

<KitSettingField Setting="@setting" Fields="@Posted" Error="@error">
    <div class="kit-settings-actions">
        <KitButton Type="submit" name="op" value="save">Save</KitButton>
    </div>
</KitSettingField>

Dialogs and confirms

KitDialog renders the browser's own <dialog>, which gives the backdrop, the focus trap and Escape. Variant is Modal, a box in the middle that rises as it opens, or Drawer, a panel the screen's full height at its inline-end edge that slides in; both are still under reduced motion. It is labelled by its Title, and its close button closes it and posts nothing (formmethod="dialog" and formnovalidate).

Any element with data-kit-open="<id>" opens the dialog of that id, which kit.dialog.js looks up at the click, so a dialog an enhanced navigation removed is simply not opened. A click outside the dialog's box, on the backdrop, closes it. An opener inside a popover hides the popover first, and the popover's trigger takes the focus back when the dialog closes.

<KitButton data-kit-open="remove" data-kit-fill-user-id="@user.Id" data-kit-fill-name="@user.Name">Remove</KitButton>

<KitConfirm Id="remove" Title="Remove this user?" FormAction="~/users/remove" FormName="remove-user"
            Fields="@(["user-id"])" ConfirmText="Remove">
    <p><span data-kit-slot="name"></span> is signed out and cannot sign in again.</p>
</KitConfirm>

Before it opens, the script clears every marked target it can fill, then copies each data-kit-fill-<name> of the opener, as text, into the target of that name, matched ignoring case. A target is an element with data-kit-slot="<name>", or a control marked data-kit-fillable that is a textarea or an input of one of six types: hidden, text, search, email, tel or url. A marked control of any other type (a checkbox, a radio, a file input, a number) or a select is never cleared or filled. Only marked fields are filled, so a form the server filled in a dialog keeps its values; KitConfirm marks its hidden fields. One dialog can serve a whole list this way, and it never shows or posts the last row's values. A name is lower-case letters and digits joined by hyphens. A name starting _ is never filled, so a row cannot overwrite the form's _handler or its antiforgery token. An opener marked aria-disabled="true" opens nothing.

With FormAction and FormName, a dialog's title, body and footer sit in one <form method="post"> with @formname and the antiforgery token, Blazor writing the form's _handler field itself; a footer button with Type="submit" posts the body's fields to the action, and a handler with that FormName receives it. The action goes through KitHref.Local: a path on this site or a ~/ path, joined to the request's path base. A refused action renders no posted form; the dialog then only closes. KitConfirm is such a dialog with a hidden field for each of its Fields, a cancel button that sends nothing, and a confirm button, Danger unless ConfirmVariant says otherwise; a confirm whose action KitHref.Local refuses throws, since a confirm must post.

A confirm posts to the page that renders it, to an endpoint that is not a Blazor page (a minimal API or an MVC action, which reads the token itself), or to a Blazor page that renders a form of the same name. A Blazor page that only binds the name, with [SupplyParameterFromForm(FormName = …)] and no such form, answers the post with 400.

A component that handles its own confirm passes OnConfirm. The confirm's form is then a named form with that handler on it (KitDialog's OnSubmit), so the post runs the handler in the request that renders the page again, after the component has bound the fields with [SupplyParameterFromForm(FormName = …)]. The confirm must be rendered in that request too, or Blazor answers the post with 400. Without OnConfirm the form carries no handler, as before.

Row menus

KitMenu renders a row menu on the browser's own popover: a trigger, a ghost KitButton with popovertarget and aria-haspopup="menu", showing three dots with its Label as aria-label (or its label as text with ShowLabel), and a popover panel with role="menu". The browser opens the panel and closes it on a click outside it or on Escape; kit.menu.js places it under its trigger and inside the viewport, focuses its first item, and moves among the items with the arrow keys, Home and End. Each row's menu needs its own Id, unique on the page.

@foreach (var user in users)
{
    <KitMenu Id="@($"user-{user.Id}-menu")" Label="@($"Actions for {user.Name}")">
        <KitMenuItem Href="@($"~/users/{user.Id}")">Open</KitMenuItem>
        <KitMenuItem OpenDialog="remove" data-kit-fill-user-id="@user.Id" data-kit-fill-name="@user.Name" Danger>Remove</KitMenuItem>
        <KitMenuItem Action="~/users" FormName="disable-user" name="user-id" value="@user.Id">Disable</KitMenuItem>
    </KitMenu>
}

<KitMenuForm FormName="disable-user" Action="~/users" OnSubmit="Disable" />

Each KitMenuItem, role="menuitem", is one of four kinds:

  • a link, Href through KitHref.LocalOrHttps;
  • a dialog opener, OpenDialog naming a KitDialog or KitConfirm, with its data-kit-fill-<name> values written on the item as on any opener; the dialog script hides the menu first and gives its trigger the focus back on close;
  • a post button, which submits the KitMenuForm of its FormName (form=) to its own Action (formaction=, through KitHref.Local), with the name and value written on the item: the pressed row's value alone is posted;
  • a theme choice, ThemeChoice light, dark or system, a role="menuitemradio" that kit.theme.js switches as it switches a KitThemeSwitch choice, aria-checked on the theme the server read.

The page places one KitMenuForm for each FormName, outside any form, since a form inside a form is dropped and Blazor refuses a post to a page holding two forms of one name. It is hidden, and carries the action, the @formname and the antiforgery token, Blazor writing the _handler field itself; its OnSubmit runs when the form is posted to the page and may redirect. A post item whose FormName has no KitMenuForm on the page would submit nothing, so kit.menu.js shows it disabled, at start and after every enhanced navigation, and warns in the console which form id is missing. The KitMenuForm must sit outside any form: inside one it is dropped, its fields join the enclosing form, and a GET form would put the antiforgery token in the url. A post item may post to the page that renders its KitMenuForm, to an endpoint that is not a Blazor page (a minimal API or an MVC action, which reads the token itself), or to a Blazor page that renders a KitMenuForm of that name; a Blazor page that only binds the name, with [SupplyParameterFromForm(FormName = …)] and no such form, answers the post with 400.

A target KitHref refuses renders the item as disabled text (aria-disabled="true"), which takes no focus. Danger marks a destructive item. Every other attribute lands on the item's element; a url attribute and a name starting _ are refused.

The admin shell

KitShell is the layout an app's layout wraps its pages in. It renders, in order, a skip link to the main region, a side rail (<nav aria-label="Main">) with the Brand and the Menu, a top bar holding the user's menu, and <main id="kit-main"> holding the page, with any Messages above it as KitAlerts. It adds no script.

@inherits LayoutComponentBase

<KitShell Brand="Elfrique Admin" Menu="@menu" UserName="@user.Name" Messages="@messages"
          SignOutAction="~/account/sign-out" SignOutFormName="sign-out" OnSignOut="SignOut">
    @Body
</KitShell>

@code {
    private IReadOnlyList<KitNavItem> menu =
    [
        new("dashboard", "Dashboard", "~/", Current: true),
        new("people", "People", Children: [new("users", "Users", "~/users"), new("roles", "Roles", "~/roles")]),
    ];
}

A KitNavItem has a Key, its text, an href, children and Current. An item with children is a group, a native <details> with a chevron, open when it holds the current item; a group with an href too is refused, naming its Key. The current item carries aria-current="page" and shows it by weight and the surface's soft fill, never the ink. An href goes through KitHref.Local, since a menu is often stored rows an administrator can edit: an item with no href (one an on-click function drove, say) is text and logs nothing, and one whose href KitHref.Local refuses is text and writes one Warning naming the item's Key, never its href, under the Solhigson.Admin.Components.KitShell category on every render. Every Key must be an id token: set, with no white space, control or format character, so a Key can forge no log line.

The user's menu, a KitMenu labelled with UserName, holds the three theme choices and sign-out. Sign-out is a post, never a link: a post item submitting the KitMenuForm the shell places after itself, outside any form, built from SignOutAction (through KitHref.Local, which must accept it) and SignOutFormName. Sign-out posts either to a page rendering the shell, where Blazor checks the token and OnSignOut runs and may redirect, or to an endpoint that is not a Blazor page (an MVC action or a minimal API), which checks the antiforgery token and signs out itself. The theme choices are menuitemradio items; the checked one shows a tick.

The rail is soft grey (--kit-ink-soft). At 720px and under it is one row above the page that scrolls inside itself, so the page never scrolls sideways. An item under the pointer takes the text colour; the current one also takes the surface's fill and is heavier. The skip link is hidden as .kit-sr text is until a keyboard focuses it. Its href is the page's own url and #kit-main, so it stays on the page under a <base href>, where a bare #kit-main would resolve against the base. The url is the one the browser asked for, the original one on a re-executed status code page, through KitHref.Local, and a url it refuses leaves the bare #kit-main; it carries data-enhance-nav="false", so Blazor does not fetch the page again for it.

The menu from permissions

IKitMenuSource builds the shell's menu from the permissions the signed-in user's roles hold, read through the framework's PermissionManager (its cached menu read, and its cached read of every permission a role holds). Register it beside the identity manager, with the same type arguments:

builder.Services.AddSolhigsonIdentityManager<AppUser, AppDbContext>();
builder.Services.AddSolhigsonAdmin<AppUser, AppDbContext>();

AddSolhigsonAdmin<TUser, TKey, TContext>() is the overload for a key type other than string. Either registers the menu source, the users seam (see Users) and the audit seam, all scoped (see Recording changes), and IHttpContextAccessor, which the audit seam reads the signed-in user through, and nothing else. The layout passes the menu to KitShell, and says so on the page when it could not be read, since an empty rail would otherwise read as a revoked grant:

@inherits LayoutComponentBase
@inject IKitMenuSource MenuSource

<KitShell Brand="Elfrique Admin" Menu="@_menu.Items" Messages="@_messages" UserName="@HttpContext!.User.Identity?.Name"
          SignOutAction="~/account/sign-out" SignOutFormName="sign-out">
    @Body
</KitShell>

@code {
    private KitMenuResult _menu = new([], false);
    private IReadOnlyList<KitMessage>? _messages;

    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override async Task OnInitializedAsync()
    {
        _menu = await MenuSource.ForAsync(HttpContext!.User, HttpContext.Request.Path, HttpContext.RequestAborted);
        _messages = _menu.Failed ? [new(KitTone.Danger, "The menu could not be loaded. Reload the page to try again.")] : null;
    }
}

The menu shows; it does not enforce: each page's [Permission] is the gate. The roles are the principal's role claims, as [Permission] reads them, so the menu and the gate agree for the life of a cookie; a user who is not signed in, or who holds no role, is shown nothing. A permission the roles hold is an item, keyed by its name, its text the description or else the name, its href the stored url. A parent they do not hold is shown only as the label of a held child, and only when it is enabled; a disabled parent takes its children with it. A held parent with a url of its own and held children is a group whose first item is its own link. The order is the stored menu index, then the name. The current item is the one whose url, ~/ read as /, is the request's path without its path base, ignoring a trailing slash and case.

The source writes to none of the manager's cached answers: each item is a new object, so one user's menu never reaches another's. The answers are cached, so a grant shows when the cache next refreshes, as it does at the gate. A fault answers an empty menu with Failed set and writes one Error under Solhigson.Admin.Navigation.KitMenuSource, with the exception, the permission manager and the role names, any control or format character in a name written as its \uXXXX escape; the request's cancellation propagates and logs nothing. A permission whose name is no id token, which KitShell cannot key an item by, is left out with its children, and named by its id in one Warning.

Page header, lead, empty state and pager

A list screen opens, reads and pages the same way: KitPageHeader holds the title as the page's one <h1> (in the serif face), an optional Line under it, a subtitle such as a count or a scope, no wider than the measure, and an optional Actions slot at the title's end, which moves under the title when the header is 400px wide or less. A line that holds more than text, such as an email and a quiet link back to a list, is LineContent, markup shown in the line's place and style; when it is set, Line is not shown. A screen's purpose sentence is not the header's line: it is KitLead, a page's or a section's one lead sentence, at a section heading's size; it is a paragraph, never a heading.

<KitPageHeader Title="Users" Line="@($"{page.Total} users, {page.Invited} invited")">
    <Actions>
        <KitButton Variant="KitButtonVariant.Primary" Href="~/users/new">New user</KitButton>
    </Actions>
</KitPageHeader>
<KitLead>Who can sign in to the admin, and what each may do.</KitLead>

@if (page.Rows.Count == 0)
{
    <KitEmptyState Title="No users match" Line="No user matches these filters." ClearHref="~/users" />
}

<KitPager NextHref="@(page.NextHref)" FirstHref="@(page.FirstHref)" />

The hrefs are written @(page.NextHref): Razor reads a bare @page as the page directive.

KitEmptyState says what is empty and why, its title an <h2>, with an optional Action (such as a link to create the first row). With ClearHref it is the "no match for these filters" form and offers a "Clear filters" link; without it, the "nothing here yet" form, which offers the next step:

<KitEmptyState Title="No roles yet" Line="A role groups the permissions a user may hold.">
    <Action>
        <KitButton Variant="KitButtonVariant.Primary" Href="~/roles/new">Create the first role</KitButton>
    </Action>
</KitEmptyState>

A list whose viewer cannot add rows shows no action, and names in its Line who can: "An administrator adds roles." The empty state's action is Primary only when the header holds none: when the header already offers it, the empty state's button is Default, or the empty state leaves the action to the header, so a screen has one Primary action.

KitPager pages a keyset list with links: forward to NextHref, which carries the next page's cursor, and back to FirstHref; a keyset cursor has no previous page. With both it shows "First page" and "Next page"; with NextHref alone, the first page of several, "Next page"; with FirstHref alone, the last page, "First page" and "End of list"; with neither, nothing. Every href goes through KitHref.Local and a refused one renders no link; a refused NextHref shows no link and no "End of list", since the list may go on. A cursor in a link shows in the address bar, so it holds ids and instants alone, as the framework's do.

Data table and filter bar

KitTable<TRow> lists Rows under KitColumn<TRow>s, each a sentence-case Title and a cell, a template over the row that holds components and text, which Razor encodes: a cell is never an HTML string. Align="KitAlign.End" ends a column of numbers and sets them in tabular figures; Priority="KitPriority.Low" hides a column when the table is 720px wide or less, so a phone keeps the columns that matter in view, and the table scrolls sideways inside its own wrapper rather than widening the page. The columns are collected before the table is drawn, so one static render shows every header and cell; a column takes its row type from its table. Caption names the table for a screen reader, and shows with ShowCaption; Empty shows in the table's place when there is no row.

<KitTable Rows="@users" Caption="Users">
    <Empty>
        <KitEmptyState Title="No users match" Line="No user matches these filters." ClearHref="~/users" />
    </Empty>
    <ChildContent>
        <KitColumn Title="Name">@context.Name</KitColumn>
        <KitColumn Title="Status"><KitStatusPill Tone="@context.Tone" Text="@context.Status" /></KitColumn>
        <KitColumn Title="Sign-ins" Align="KitAlign.End" Priority="KitPriority.Low">@context.SignIns</KitColumn>
        <KitColumn Title="Actions" HideTitle Align="KitAlign.End">
            <KitMenu Id="@($"user-{context.Id}-menu")" Label="@($"Actions for {context.Name}")">
                <KitMenuItem Href="@($"~/users/{context.Id}")">Open</KitMenuItem>
            </KitMenu>
        </KitColumn>
    </ChildContent>
</KitTable>

HideTitle keeps a column's header for a screen reader alone, for a column whose cells say what they are, such as a row's menu. There is no sort or row-open script: a sortable column is a link the app writes in its cells or above the table.

KitFilterBar is a plain form around the app's KitFields, with an "Apply" button, a Default one since the screen's Primary action stays the header's, and, with ClearHref, a "Clear" link; it wraps onto as many rows as the width needs, and opts in to enhanced form handling (data-enhance), so the list is swapped in place. Method is KitFormMethod.Get unless set, so a filtered list has an address a user can keep and share. A filter on a personal value, such as an email or a name, uses Method="KitFormMethod.Post", so the value stays out of the address, the access log and the browser's history; a Post filter takes a FormName, its @formname, and carries the antiforgery token, Blazor writing the _handler field itself, and the page binds the fields with [SupplyParameterFromForm(FormName = …)]. Action, the page's own address when unset, and the clear link go through KitHref.Local: an Action it refuses throws, and a refused clear link is not shown. A list filtered by a Post keeps its filter on the server, in the session or behind an opaque server-side cursor, so the pager's links carry no personal value; or it is one page, with no pager. Id, when set, is the form's id, so a submit button elsewhere on the page can name the form (form="...") and post its fields; an Id holding white space, a control or a format character throws.

<KitFilterBar ClearHref="~/users">
    <KitField Name="role" Label="Role" Kind="KitFieldKind.Select" Options="@roles" Value="@Role" />
</KitFilterBar>

<KitFilterBar Method="KitFormMethod.Post" FormName="find-user" ClearHref="~/users">
    <KitField Name="email" Label="Email" Kind="KitFieldKind.Email" Value="@Email" />
</KitFilterBar>

The settings screen

KitSettingsEditor is the settings screen: every setting the app's catalogue declares, one section a group in the order the catalogue registered them, each setting a KitSettingField row in a box whose id is kit-setting- and its key, written as a field's id writes a name. Its header, titled "Settings", counts the settings and, when a setting carries a flag or the table holds a row no setting declares, links to the "needs attention" filter, saying how many. Above the groups it shows a warning that a secret's save is refused while the legacy encryptor is in force and a setting is a Secret or stored sensitive; the attention view also says how many stored rows match no declared setting, and that a row is cleared when the app declares it in its catalogue, or it is removed from the settings table. Under the groups, the section "Rows with no declaration" lists those rows (see Removing a row no setting declares). A GET filter bar finds settings by words in their key, name or purpose, never in a value, and by "needs attention". A component cannot be given a route, so the app writes the page:

@page "/admin/settings"
@using Microsoft.AspNetCore.Authorization
@using Solhigson.Framework.Web.Attributes
@using Solhigson.Framework.Web.Authorization
@attribute [Permission("settings.view")]
@inject IAuthorizationService Authorization

@if (canEdit is bool edit)
{
    <KitSettingsEditor CanEdit="@edit" />
}

@code {
    private bool? canEdit;

    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override async Task OnInitializedAsync()
    {
        var decision = await Authorization.AuthorizeAsync(HttpContext!.User, PermissionPolicy.For("settings.edit"));
        canEdit = decision.Succeeded;
    }
}

The page's [Permission] lets a viewer see the screen; CanEdit, false unless set, is a second permission's, decided on the server. Without it a Personal value is shown as "Hidden", and the listing is read outside a write session; with it the value is in its field. A Secret's value is never written into the page, with or without it. The sample renders the editor once canEdit is decided. An editor whose CanEdit changes lets a read in flight end and reads the listing again, and a render, a streamed one included, shows only a listing read with the CanEdit in force, so none shows a Personal value that CanEdit forbids; a read that failed is not made again, so one fault is one Error and one alert.

The app must have called RegisterSolhigsonDependencies with a database (or RegisterSolhigsonDependenciesWithProvider), which registers the SolhigsonConfigurationService and the ConfigurationWrapper the editor injects. It registers its settings catalogue at start (SolhigsonConfigurationService.UseSettingsCatalog); until it does, the screen shows the empty state "No settings are declared", and a registered catalogue that declares nothing shows "The catalogue declares no setting". AddRootEncryption at start lifts the warning on a secret's save.

The page refuses framing, so no other site can lay the screen under a decoy. The app must send X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on this page; the framework and the template send neither, and the editor sets no header.

A listing that cannot be read shows a Danger alert, "The settings could not be loaded", and writes one Error under Solhigson.Admin.Components.KitSettingsEditor, naming the component, with the exception; the page holds none of its text. The request's own cancellation propagates and logs nothing.

Saving and resetting a setting

With CanEdit true, every line is a form of its own. The form posts to the page's path and the row's id, without the filter's query, so the posted line is on the page whatever filter it matched. Each form sits in a FormMappingScope named from its key, and Blazor writes its _handler, such as [SignIn_003AMaxAttempts]setting; the form also holds the antiforgery token, the key and the field. A line shows:

  • "Save" when it can be edited, but a toggle. A toggle shows no "Save": it saves when it changes. Its "Save" is inside <noscript>, for a browser that runs no script. A toggle that can also be reset has a visually hidden "Save" as its form's first submit button, so Enter in the form saves it and never resets it. The button is clipped to nothing (kit-sr) rather than not rendered, since a browser may skip a button with no box when Enter submits; it is out of the tab order (tabindex="-1") and of the accessibility tree (aria-hidden="true").
  • "Reset to default" when the listing calls it resettable. A Secret shows it only while a row of it that no read sees is stored.
  • The reset alone when it cannot be edited but can be reset, such as a Startup setting's row.
  • No button when it can be neither saved nor reset. Its form is still there, so a form posted after its line lost its last button is answered at the line.

Every button is named op, its value save or reset; the alerts and buttons sit under the field, in its column.

With CanEdit false no form is rendered, so a post gets the framework's 400 and nothing is written. The handler also checks CanEdit before any call, so a post that reaches it in another way writes nothing.

A line whose value may be shown also posts the row state it was loaded with. The save passes that state on as its SettingLoad, so a save of a row changed since the page loaded is refused. A Secret, or a row stored sensitive, posts no row state. A post whose key is not its form's, whose row state the page did not write, or whose button no form has, saves nothing and says "This form is out of date: nothing was saved."

The outcome is said at the line:

Outcome Shown as
Saved A Success alert, "Max attempts saved."
Reset A Success alert that names the value now in force.
No change, or no row to reset A Neutral note that nothing changed.
A Secret posted blank A Neutral note that the stored secret was kept.
Refused The sentence beside the field, which keeps what was typed but never a secret's. A line with no field shows it in a Warn alert. The sentence names the setting by its label and says what to enter, such as "Enter a whole number from 1 to 10.", never the key in brackets or the declaration's terms.
Changed since the page loaded A Warn alert that nothing was saved and names the value now stored, which the field then shows.
Failed A Danger alert that nothing was saved, with no exception text.
Cache not told A Warn alert that other instances may show the old value until their settings cache recovers.

A setting no longer declared when its save runs has no line, so its outcome is said above the groups.

Removing a row no setting declares

Under the groups, the section "Rows with no declaration" lists each stored row the catalogue does not declare in a KitTable: its name, and its flags as the setting field's short pills, such as "Looks secret". No value is shown, since nothing says whether such a row holds a secret. The filters leave the section as it is, so the "needs attention" view shows it too. The section is not rendered when no catalogue is registered, when the catalogue declares no setting, or when no such row is stored: with no catalogue every row would be listed.

With CanEdit true, each row has a "Remove" button. It opens one KitConfirm, "Remove this row?", filled with the row's name: "The row … matches no declared setting. Older code may still read it by name, and this screen cannot put it back." The confirm's "Remove row" posts the name to the page's path and the section's id, #kit-settings-stray. The editor handles the post itself (OnConfirm), with the handler stray-remove. It checks CanEdit before any call, then calls the framework's RemoveUndeclaredRowAsync, which judges the name again: a name a setting declares, or a row the database matches to one, is refused. The confirm is rendered whenever a removal could be made, so a confirm posted after its row went is answered; with no stray row left, the section shows its heading and the outcome alone.

The outcome is said under the section's heading, above its table:

Outcome Shown as
Removed A Success alert, "The row Retired:Banner was removed."
No such row A Neutral note, "No stored row is named Retired:Banner; nothing was removed."
Belongs to a setting A Warn alert naming the setting by its label, "Nothing was removed: SignIn:MaxAttempts belongs to the setting Max attempts. Reset that setting above instead."
Refused otherwise A Warn alert with the framework's sentence, opening "The row Retired:Banner was not removed."
Failed A Danger alert that nothing was removed, with no exception text.
Cache not told A Warn alert, as for a save.

With CanEdit false neither the buttons nor the confirm are rendered, so a post gets the framework's 400 and nothing is removed; the handler's own check covers a post that reaches it another way. Neither is rendered either when KitHref.Local refuses the page's path as the confirm's action, such as a path holding an escaped backslash that reaches the page by an optional route part.

Recording who changed a setting

Each save, reset or removal done is recorded through the audit seam, IKitAudit (see Recording changes), after it is done. The audit row holds:

  • the category SecurityEvent;
  • the action settings.saved, settings.reset or settings.stray-removed (KitAuditActions);
  • the entity type AppSetting, with the setting's key, or the removed row's name, as both the entity id and the subject's display name;
  • the actor;
  • a payload of the key, PreviousShown and NewShown, the values before and after as the framework's result shows them. A Secret's value, a row stored sensitive and a Personal value are the mask. A removal's NewShown is null, and its PreviousShown is the value removed: the mask for a row stored sensitive or under a secret-looking name, else the value, which is what a developer puts back.

A refusal, no change, a change made elsewhere and a failed save or removal change nothing, and record nothing.

When the record cannot be written, the change is not undone. The two are written by different contexts, so the screen shows the Success alert and a Warn alert: "No audit record was written for this change. Record it by hand if the audit trail must hold it; the app's log holds the error." A reset's says "this reset", a removal's "this removal".

When no change can be recorded, the screen shows a Warn alert above the groups with CanEdit true, titled "Changes here leave no audit record". The read-only screen, where nothing changes, does not show it. No change can be recorded when:

  • IKitAudit is not registered;
  • no audit service resolves;
  • the app's context does not map AuditTrail and no IAuditSink is registered.

The record is written with no cancellation, so a save is recorded even when the operator has left the page.

The screen writes one log line, under Solhigson.Admin.Components.KitSettingsEditor. The audit seam writes its own lines under Solhigson.Admin.Auditing.KitAudit (see Recording changes). The save, the reset and the removal write theirs under Solhigson.Framework.Infrastructure.ConfigurationWrapper, with the setting's key and never its value when the value may not be shown. The settings cache's invalidation writes under Solhigson.Framework.EfCore.Caching.EfCoreCacheManager, and its Redis change tracker under Solhigson.Framework.EfCore.Caching.MemoryCacheProvider:

Line Level Text What to do
KitSettingsUnlisted Error {Component} could not read the settings listing, so the page shows that the settings could not be loaded. Read the exception; fix the database or the catalogue it names.
Saved Information The setting [{setting}] was saved: {previous} to {saved}; cache confirmed {cacheConfirmed}. Nothing. A False means other instances may show the old value until their cache recovers.
Reset Information The setting [{setting}] was reset: {removed} row(s) removed, {previous} to {inForce}; cache confirmed {cacheConfirmed}. As for Saved.
Removed Information The undeclared row [{setting}] was removed; cache confirmed {cacheConfirmed}. As for Saved.
Not declared Warning A {save|reset} named the setting [{setting}], which is not declared; nothing was {saved|reset}. Declare the setting in the catalogue, or stop posting it.
Not done Warning The setting [{setting}] was not {saved|reset|removed}: {reason} Act on the reason: a setting read at start is changed in configuration; a row nothing would answer without keeps its value; a declared setting's row is reset, not removed.
Refused Warning The setting [{setting}] was not {saved|reset|removed}: {rule}. Act on the rule: a value in bounds, a page loaded again, or AddRootEncryption for a secret.
Saved plain Warning The setting [{setting}] is saved plain although its name {reason} (term '{term}'): its value is a flag or a number. Check the name does not hold a secret.
No catalogue Warning No settings catalog is registered (SolhigsonConfigurationService.UseSettingsCatalog), so a settings table write is held to no declaration, only to the encryptor and secret-name rules. Logged once per process. Register the catalogue at start.
Failed Error {Saving|Resetting|Removing} the setting [{setting}] failed. Read the exception; the screen said nothing was done, so the operator tries again.
Cache timed out Warning [{CacheType}]: Invalidation of {Types} did not complete within {Timeout} The value is stored; other instances may serve the old value until their cache entry expires. Check the cache store (Redis) and its latency.
Cache failed Warning [{CacheType}]: Invalidation of {Types} failed Read the exception; as for a timeout, other instances may serve the old value until their cache entry expires.
Cache not invalidated Error [{CacheType}]: Unable to invalidate cache A fault other than Redis's in the save's own invalidation (the EF Core interceptor's). Read the exception; other instances may serve the old value until their cache entry expires.
Change tracker unavailable Warning Change tracker unavailable: {Kind} ({Reason}) on {Channel}; entries cached before the outage are served until they expire or the tracker recovers, nothing new is cached, and the poll retries Redis every {Interval}; a writer should use InvalidateAndWaitAsync to confirm a change was published Logged once per outage, by the first call that finds Redis down, the save's invalidation included; a Redis failure the save meets writes neither "Cache failed" nor "Cache not invalidated". Restore Redis; until then the screen says the cache was not told.
Change tracker available again Warning Change tracker available again: Redis answered; {Lost} invalidations were lost on this pod during the outage ({Resend}) Closes the outage, once. Nothing, unless the lost invalidations were not sent again.

Recording changes

IKitAudit (Solhigson.Admin.Auditing) is the one seam through which every admin screen records a change it made. AddSolhigsonAdmin registers it, scoped, as KitAudit<TContext> over the app's identity context TContext. The app must map AuditTrail in that context's OnModelCreating and migrate, or register an IAuditSink that writes the rows elsewhere. The framework's RegisterSolhigsonDependencies registers the audit service, IAuditTrailService<TContext>. That registration is made through Autofac, which the service collection does not see. So the seam resolves the audit service, the actor provider and the context from the request's services at first use, not at registration.

TContext must be registered scoped, as AddDbContext and the framework's Autofac module register a context. The seam looks for an unsaved row on the instance it resolves, which must be the one the framework's service wrote on.

  • Records is false when no audit service resolves, or when the context does not map AuditTrail and no IAuditSink is registered. The framework's service would then drop the row with a log line, so the seam does not say a row was written. A screen asks Records to say on the page that its changes are not recorded. An app that never called AddSolhigsonAdmin gets a seam whose Records is false.

  • RecordAsync(KitAuditEvent, CancellationToken) writes one row and answers whether it was written; handed to the app's sink counts as written. It throws only the caller's own cancellation. A write that throws is logged and answered false. The framework's service swallows a failed write, so the seam also answers false in two cases:

    • A row the service left unsaved on the context. The seam detaches it, so no later save in the request writes it.
    • A sink that threw. With a sink and the framework's own service, the seam writes through an instance of that service of its own, over the app's sink behind a watch, and reads what the handoff threw. The container's registrations are left as they are, so no other caller resolves the watch.

    With an audit service of the app's own in place of the framework's, the seam answers false for what that service throws, and cannot see what it swallows: a write it swallows is answered true.

  • KitAuditEvent carries the category, the action, the subject's entity type, id and display name, and the payload. The payload is stored as it is: the framework masks nothing on this path, so a screen passes a projection that holds only what the row may show.

  • The actor is the app's IAuditActorProvider's. The framework's default provider gives the unattributed actor. When it does, the actor is built from the request's principal, and its source is web. Its id is read as the users seam reads the acting user (see The acting user): the first claim of Identity's ClaimsIdentity.UserIdClaimType (NameIdentifier unless the app sets another), counted only when the identity that holds it is signed in. Its name is that identity's. With no such id, the name is the principal's own identity's when it is signed in. An app whose tokens carry the id as sub sets UserIdClaimType to sub. A provider of the app's own that names an actor is used as it is.

The seam writes these lines under Solhigson.Admin.Auditing.KitAudit, with the entity id (a setting's key) and never the actor or a value:

Line Level Text What to do
KitAuditOff Warning Admin changes are not recorded in the audit trail: {Reason} Each admin screen that changes data says so above its content. Logged once per process. Act on the reason: register the audit service (RegisterSolhigsonDependencies), map AuditTrail in the context and migrate, or register an IAuditSink; call AddSolhigsonAdmin when the seam is not registered. A reason that the service could not be resolved carries the exception.
KitAuditFailed Error The audit row of {Action} on [{EntityId}] was not written: {ExceptionType}; the change itself was made, and is not undone. The line names the exception's type only, never the exception or its message, which can hold what the row held. Read the audit service's or the sink's own log for the cause, and fix the audit store. The change has no audit row, so record it by hand if the audit trail must hold it.
KitAuditUnsaved Error The audit row of {Action} on [{EntityId}] was not written: the audit service left it unsaved, and its own log line holds the cause; the change itself was made, and is not undone. Read the framework's line under AuditTrailService, "Explicit audit event was swallowed under the never-block invariant", for the exception, and act as for KitAuditFailed.

Users

IKitUsers (Solhigson.Admin.Users) is the one seam through which the user screens read and change users. A screen injects this one type, whatever the app's user and key types. AddSolhigsonAdmin registers it, scoped, over the framework's UserAdministration that AddSolhigsonIdentityManager registers with the same type arguments:

  • AddSolhigsonAdmin<TUser, TContext>() (string keys) closes it over SolhigsonAspNetRole and string.
  • AddSolhigsonAdmin<TUser, TKey, TContext>() closes it over SolhigsonAspNetRole<TKey> and TKey.

A seam the app registered first is kept. The framework decides every reach; the seam adds no rule and hides no outcome. The app must register its IUserAdministrationRules<TUser, TKey>, else every call answers NoRules.

Member Answers What it reads
SearchAsync(principal, search, ct) KitUserPage (Rows, NextCursor, Outcome, Message) The framework's search. Every member of KitUserSearch (Text, Role, Enabled, LockedOut, TwoFactorEnabled, NotSignedInSince, HasPassword, Cursor, PageSize) is passed on as it is.
GetAsync(principal, userId, ct) KitUserLookup (Row, Outcome, Message) The framework's CanAdministerAsync. The row is the user it reached, as stored, with no second read; an edit the request has not saved does not show. The app's DisplayName is given a copy that no context tracks, with the password hash and stamps null, so a write to it is never saved. The roles are read from the database for the call, never a cache.
GrantableRolesAsync(principal, ct) KitRoleNames (Names, Outcome, Message) The framework's GrantableRolesAsync: the roles the acting user may grant.
RoleNamesAsync(ct) KitRoleNames Every stored role's name, ordered.
SetEnabledAsync(principal, userId, enabled, ct) KitUserResult (Outcome, Message, UserId, EndSessions, NeedsPasswordLink) The framework's SetEnabledAsync, which checks reach, refuses the acting user's own account (NotOwn) and answers Unchanged when the user already is as asked. A disable rotates the security stamp and answers EndSessions; so does a disable answered Unchanged. An enable answers NeedsPasswordLink when the user has no password. The seam passes these on and acts on neither: the caller ends the sessions and asks for the link.
UnlockAsync(principal, userId, ct) KitUserResult (Outcome, Message, UserId) The framework's UnlockAsync on the user's id, which checks reach, refuses the acting user's own account (NotOwn) and acts on the row it loaded, never on a user looked up again by name. A user not locked out answers Unchanged. A lockout by wrong authenticator codes is Identity's lockout end, so it ends too, and the code counters are cleared where two-factor is registered. The seam writes no audit row: the caller does.
ResetTwoFactorAsync(principal, userId, ct) KitUserResult (Outcome, Message, UserId, EndSessions, HadPassword, TwoFactor) The framework's CanAdministerAsync on the user's id first. The seam then loads the acting user by the principal's id: one that no longer loads answers ActorRefused, and one whose stored key is the reached user's answers NotOwn, whatever form the id takes (a braced Guid, say). The user it reached, never one looked up again, then goes to the two-factor manager's ResetAsync with the acting user's id as Identity writes it. The manager refuses the acting user's own account again (NotOwn) and a user not enrolled (NotEnrolled); otherwise it removes the authenticator, the password and any lockout end, rotates the security stamp and answers EndSessions and HadPassword. TwoFactor holds the manager's outcome and Message its sentence; a reach refusal leaves TwoFactor null. A host with no two-factor answers Failed before any read. The seam writes no audit row, ends no session and sends no notice: the caller does.
SetRolesAsync(principal, userId, roles, loadedRoles, ct) KitUserResult (Outcome, Message, UserId, EndSessions, Granted, Revoked, Disabled, Stale) The framework's CanAdministerAsync on the user's id first, then the acting user loaded, as for ResetTwoFactorAsync (ActorRefused, NotOwn by the stored keys). The seam then reads the user's roles from the database and compares them with loadedRoles, the roles the page was rendered with. It compares sets of names normalized as Identity normalizes a role's name (RoleManager.NormalizeKey, upper case by default), so case, order and repeats do not count; Identity and the framework take names that differ only by case as one role. When the sets differ, the answer is Stale with Unchanged, the user's id, and nothing written. Otherwise the framework's SetRolesAsync decides (see Changing a user's roles). Done carries the names granted and revoked, Disabled and EndSessions. The comparison is a read before the write, not a lock: a change between the two is the framework's own crossing-write refusal, IdentityFailed. The seam writes no audit row, ends no session and sends no notice: the caller does.
ChangeEmailAsync(principal, userId, newEmail, ct) KitUserResult (Outcome, Message, UserId, EndSessions, PreviousEmail) The framework's ChangeEmailAsync, which decides everything (see Changing a user's email): EmailChangeOff unless the app turned the change on, then the reach and the acting user's own account (NotOwn) by the stored keys, then RoleOutOfReach when the user holds a role the acting user may not grant, then InvalidEmail, Unchanged for the address held, and EmailInUse. Done carries EndSessions and the address it replaced as PreviousEmail; the new address starts unconfirmed. RoleOutOfReach here has its own sentence, about the roles the user holds. Neither address goes in a log line. The seam writes no audit row, ends no session and sends no notice: the caller does.
CreateAsync(principal, newUser, ct) KitUserResult (Outcome, Message, UserId, NeedsPasswordLink, Granted, Disabled, BuildRefused) The app's IKitUserFactory<TUser>, else the package's default, builds the user from KitNewUser (Email, Phone, Roles, Form; see Building the new user). A refusal of the factory's answers Failed with BuildRefused and its sentence, nothing written. A string id the build left null or empty is a new sequential Guid. The seam reads the stored names of the roles asked for, at step Roles, before anything is written. The framework's CreateAsync then decides everything (see The new-user screen): NoRules, ActorRefused, EmptyRoleSet, RoleNotFound, RoleOutOfReach, RoleSetRefused, InvalidEmail, EmailInUse, NotFound for a new user outside the acting user's reach, which it rolls back and which has its own sentence, IdentityFailed and Failed. Done carries the new id, NeedsPasswordLink, the roles asked for as Granted (each once, under its stored name, so "CLERK" is recorded as "Clerk") and Disabled when the framework started the user disabled. Neither the address nor the phone goes in a log line. The seam writes no audit row and sends no link: the caller does.
TwoFactorAvailable bool True when the framework's two-factor manager of the same closure resolves, that is, when the app called AddSolhigsonTwoFactor.
SignInNeedsConfirmedEmail bool True when an unconfirmed address keeps a user from signing in, as Identity's SignInManager decides it: SignIn.RequireConfirmedEmail is on, or SignIn.RequireConfirmedAccount is on and the app's IUserConfirmation answers by Identity's own DefaultUserConfirmation rule, which confirms an account by its address. A subclass that keeps that rule counts. A confirmation that overrides Identity's rule, or an app's own, does not count. A confirmation that throws as it resolves counts, with one Error.

The acting user

The acting user is read on the server from the principal, never from a value a page binds. Its id is the first claim of Identity's own ClaimsIdentity.UserIdClaimType, the claim UserManager.GetUserId(principal) reads. The claim counts only when the identity that holds it is signed in. A principal can hold several identities, and one signed-in identity does not vouch for an id another carries. A principal that names no acting user so answers ActorRefused and reads nothing. A screen passes the request's HttpContext.User.

Rows

A KitUserRow holds:

  • Id, as UserManager.GetUserIdAsync gives it.
  • DisplayName: the rules' DisplayName, else the email.
  • Email, EmailConfirmed and UserName.
  • Roles, ordered.
  • Enabled, TwoFactorEnabled and HasPassword.
  • LockedOutUntil: set only when lockout is on for the account and its end is after now. The clock is the registered TimeProvider, the one the framework reads.
  • LastSignIn: read as UTC.
  • IsViewer: true when the acting user's loaded key equals the row's. The keys are compared, never the ids' text.

A row holds no password hash, stamp or token. Email, UserName and DisplayName are [PersonalData]. A row's text (ToString) is its id.

Outcomes and sentences

Every answer carries the framework's UserAdministrationOutcome and a Message for the operator. KitUserMessages.For(outcome) gives one sentence for each user-administration outcome, and KitUserMessages.For(TwoFactorOutcome) one for each two-factor outcome. Show Message as it is. These outcomes matter to a reading screen:

Outcome Meaning Sentence
Done The read was made. Done.
NotFound The user is missing, or out of the acting user's reach. Both share one sentence, so an id cannot be probed. User not found.
NoRules The app registers no IUserAdministrationRules for its user and key types. Never shown as an empty list. Names the registration to add.
ActorRefused The principal names no acting user, or the framework refused it (missing or disabled). Says the account may not administer users.
Failed A step threw. A fixed sentence; the app's log holds an Error naming the step.

A write adds these outcomes:

Outcome Meaning Sentence
Unchanged The user already was as asked, such as a disable another administrator made first. Nothing was written. Nothing changed: the user was already as asked.
NotOwn The user is the acting user's own account. Says the account may not change itself.
IdentityFailed Identity refused the write. Asks the operator to reload and try again.

An email change adds EmailChangeOff, InvalidEmail, EmailInUse and RoleOutOfReach, each with its own sentence. RoleSetRefused shows the app's own reason, when the app gives one. A role change from a page whose roles changed since it was rendered answers Stale true with Unchanged, and its sentence asks the operator to reload. A create adds EmptyRoleSet, RoleNotFound, RoleOutOfReach, RoleSetRefused, InvalidEmail and EmailInUse; a refusal of the user factory's answers Failed with BuildRefused true and the factory's own sentence. KitUserResult (Outcome, Message, UserId, EndSessions, NeedsPasswordLink, Granted, Revoked, Disabled, PreviousEmail, HadPassword, Stale, TwoFactor, BuildRefused) is what each later write of the seam answers.

A two-factor reset reads the manager's outcome as one of these:

TwoFactor Outcome
Reset Done
NotEnrolled, TwoFactorOff Unchanged
NotOwn NotOwn
Any other Failed

Nothing throws except the caller's cancellation.

Auditing

KitUserAudit holds the audit vocabulary for the user screens. The entity type is User and the entity id is the user's id. The actions are users.enabled, users.disabled, users.unlocked, users.password-link-sent, users.two-factor-reset, users.roles-changed, users.email-changed and users.created. Each is recorded as a SecurityEvent through IKitAudit (see Recording changes). A payload holds no personal value but one: users.email-changed holds the address the change replaced, never the new one, since recovering a taken account needs it.

Log lines

The seam writes these lines under Solhigson.Admin.Users.KitUsers. A line carries ids only, never an email, a name or an exception's message. An id is percent-encoded, so a line break in it forges no line, and cut to 64 characters with a ... marker.

Line Level Text What to do
KitUsersNoActor Warning The users seam refused {Method}: the principal carries no {ClaimType} claim on a signed-in identity, so it names no acting user; nothing was read. Check that the page requires a signed-in user. If the user is signed in, check that the signed-in identity carries the claim ClaimType names, or set IdentityOptions.ClaimsIdentity.UserIdClaimType to the claim it does carry.
KitUsersFailed Error The users seam {Method} failed at step {Step}: {ExceptionType}; actor [{ActingUserId}], target [{TargetUserId}]. Read the step. Row means the app's DisplayName threw for the user the target names; Read means the role table could not be read; Resolve means the two-factor manager could not be built, so TwoFactorAvailable answers false, or, for reset_two_factor, the app called no AddSolhigsonTwoFactor, or, for sign_in_needs_confirmed_email, the app's IUserConfirmation could not be built, so SignInNeedsConfirmedEmail answers true; Actor means the acting user could not be read again after the reach; Build means the app's IKitUserFactory threw or answered no build for create; Reset means the two-factor manager's reset threw, such as for a user store that is not Identity's EF UserStore with AutoSaveChanges on; ActingId means the principal could not be read. Other steps (Roles, Password, Viewer) are Identity's reads; check the store.

A fault inside the framework's own call (step Call) is answered Failed by the framework, which writes its own Error under UserAdministration. The seam writes no second line for it.

The framework's lines and counters

Each call the seam makes into the framework writes the framework's own lines, by ids only, never an email, a name or a role's name. Under UserAdministration (UserAdministrationDiagnostics.LoggerCategory) it writes:

  • A Warning for a user not found within reach, a refused actor, the acting user's own account, a write Identity refused, a role the acting user may not grant, an address in use, and an unlock whose two-factor code counters were not all cleared.
  • An Error for NoRules, a step that threw, a user store it cannot rely on, and a create or a role change refused for unsaved changes of the app's own in the context, or for rows it wrote beyond what was asked.
  • An Information line for each write done.

A search, a lookup or a list of grantable roles that is answered writes no line.

A two-factor reset writes its lines under Solhigson.Framework.Identity.TwoFactor (TwoFactorDiagnostics.LoggerCategory): an Information line for a reset that landed; a Warning for a self-reset refused, a write Identity refused, a reset answered failed whose commit may have landed, and a reset read back as landed after another request saved the account; and an Error for a step that threw. Clearing the user's code counters once a reset has landed writes its Warnings under Solhigson.Framework.Identity (SignInDiagnostics.LoggerCategory), with the sign-in's lines. The XML documentation of UserAdministrationDiagnostics and TwoFactorDiagnostics lists every line.

Each call also adds one to a counter on the meter Solhigson.Framework.Identity, which the app adds to its metrics pipeline (AddMeter("Solhigson.Framework.Identity")). The package's own lines add to no counter.

Counter Tags What to watch
user_administration method: the framework's method, such as search, can_administer (the user page's lookup, and the reach of a role change and of a two-factor reset), grantable_roles, set_enabled, unlock, set_roles, change_email or create. outcome: the answer, such as done, unchanged, not_found, actor_refused, no_rules, identity_failed, failed or cancelled. failed, no_rules or identity_failed: read the framework's line under UserAdministration. A rise in not_found or actor_refused: ids out of reach, or accounts that may not administer, are being tried.
two_factor method: reset for the user page's reset. outcome: such as reset, not_enrolled, not_own or failed. failed: read the framework's Error under Solhigson.Framework.Identity.TwoFactor.

The users screen

KitUsersList lists the users the signed-in user may administer, one page at a time, through IKitUsers.SearchAsync. A component cannot be given a route, so the app writes the page:

@page "/admin/users"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("users.view")]

<KitUsersList DetailHref="~/admin/users/{id}" CreateHref="~/admin/users/new" TimeZone="@AppZone" />
Parameter Required What it does
DetailHref yes The address of a user's page: a path on this site that holds {id}. Each row's id replaces {id}, url-encoded, and the link then goes through KitHref.Local. A DetailHref without {id}, or one KitHref.Local refuses with an id in place (another site, //, .., white space), throws when the screen renders. An id that KitHref refuses, such as .., shows the name as text with no link.
CreateHref no The address of the page that creates a user. Without it the screen offers no "New user".
TimeZone no The zone the last sign-in is shown in; UTC when not set. The column's title names the zone's id.

The app must call AddSolhigsonAdmin (see Users) and register its IUserAdministrationRules. The page must require a signed-in user, since the screen passes the request's HttpContext.User. The "not signed in for" filter counts from the registered TimeProvider, else from the system clock.

The page refuses framing, so no other site can lay its search form under a decoy. The app must send X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on this page, as on the settings page; the framework and the template send neither, and the component sets no header.

The user's page receives the id already decoded: an id team/ada is linked as .../team%2Fada, and the route parameter {Id} of @page "/admin/users/{Id}" holds team/ada. Pass it to IKitUsers.GetAsync as it is.

One id cannot reach a route parameter exact: an id holding the text %2F, in either case. ASP.NET Core decodes the request's path except %2F, and routing decodes %2F after, so team%2Fada, linked as .../team%252Fada, would arrive as team/ada, another user's id. Under a {id} in the path, such an id shows its name as text with no link. An app whose ids may hold %2F puts {id} in the query, which is decoded once: DetailHref="~/admin/users/detail?id={id}", read with [SupplyParameterFromQuery(Name = "id")].

The screen has these parts, in this order:

  1. The header, "Users", with "New user" as its primary link when CreateHref is set and the page has rows.
  2. One band: the search first, then the filters.
  3. The table: the user (the name links to its page, the email under it), the roles, the status, two-factor ("On" or nothing) and the last sign-in. Two-factor and the last sign-in are hidden in a narrow table.
  4. The pager. While a search is active it is the search's own "Next page" (see below).

The status column gives colour only to what needs attention. "Enabled" is muted text. "Disabled" is a Neutral pill, and "Locked out" a Warn pill; a user who is both shows "Disabled". "No password" follows as plain text. The last sign-in is a date, with the time for today and yesterday, or "Never".

The filters are a GET form, so a filtered list has an address a user can keep:

Filter Field Values Search
Role role A name from RoleNamesAsync. When the names cannot be read the filter is not offered and a role in the address is ignored. Role
Status status enabled, locked-out, disabled enabled: enabled and not locked out. locked-out: enabled and locked out. disabled: disabled, locked out or not.
Two-factor two-factor on, off. Shown only when TwoFactorAvailable. TwoFactorEnabled
Not signed in for not-signed-in 30, 90, 180 (days) NotSignedInSince: that many days before now, in UTC.
No password no-password true HasPassword false

A value the screen does not offer is ignored. A cursor that does not parse serves the first page.

The search keeps the searched text private

A searched email or name is personal data. The search is a posted form (users-search, id kit-users-search) with the antiforgery token. Its text is never put in a link, a form's action, the address or a redirect, so it stays out of the access log and the browser's history. The post is answered on the page. The form carries the filters in force as hidden fields. While a search is active:

  • The field shows the search, with "Clear search", a link to the list under the same filters.
  • The form carries the search in force as the hidden field searched.
  • "Next page" stands under the table, where the pager does. It is a submit button of the search's form (form="kit-users-search"); its value is the next page's cursor. A posted cursor pages the searched search, so text edited into the field since is not paged; Search searches it.
  • Enter in the field presses the form's own "Search", so it searches and never pages.
  • Applying a filter is a GET, so it ends the search.

A posted search cannot be bookmarked. The screen writes no log line.

Empty states and refusals

With no rows and nothing narrowing the list, the screen shows "No users yet", with "New user" as its action when CreateHref is set. With a search or a filter in force, it shows "No users match", with a link that clears them. With a cursor alone it says "No users on this page.", with a link to the first page.

When the seam answers NoRules, ActorRefused or Failed, the screen shows a Danger alert, "Users could not be listed", with the seam's Message, and no table. The role filter is then not offered.

The user page

KitUserDetail shows one user through IKitUsers.GetAsync. It answers one question first: can this user sign in, and if not, why. The app writes the page, with the user's id in its route:

@page "/admin/users/{Id}"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("users.view")]

<KitUserDetail UserId="@Id" ListHref="~/admin/users" TimeZone="@AppZone" />

@code {
    [Parameter]
    public string? Id { get; set; }
}
Parameter Required What it does
UserId yes The id of the user to show, as the route gives it.
ListHref yes The address of the users list, a path on this site. The header's "All users" link and the not-found page's way back go to it. A ListHref that KitHref.Local refuses (another site, //, .., white space) throws when the page renders.
TimeZone no The zone the page's times show in; UTC when not set. Each time names the zone's id.
CanManageAccess no Whether the viewer may change the user's access: enable, disable, unlock, reset. False unless set.
CanConfigure no Whether the viewer may change the user's roles and email. False unless set.

The page must not use stream rendering: no @attribute [StreamRendering] on it or on a layout around it. A page that streams sends its status before the lookup returns, so a user not found is answered with 200, not 404. That page shows the header "Users" and the empty state "User not found", with "All users" as its action.

ASP.NET Core 10 sends a page that sets 404 with no body: it leaves the answer to the app's status code pages. Add them, such as app.UseStatusCodePagesWithReExecute("/not-found"), or the browser shows an empty page.

The app must call AddSolhigsonAdmin (see Users) and register its IUserAdministrationRules. The page must require a signed-in user, since the page passes the request's HttpContext.User. Times count from the registered TimeProvider, else from the system clock.

The page refuses framing, so no other site can lay the forms that change a user under a decoy. The app must send X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on this page, as on the settings page; the framework and the template send neither, and the component sets no header.

What the page shows depends on the seam's outcome:

Outcome Status The page
Done 200 The user, as below.
NotFound 404 No body (see above). A user who does not exist and one outside the viewer's reach give the same answer, so an id cannot be probed.
NoRules, ActorRefused, Failed 200 The header "Users", "All users" in its line, and a Danger alert, "The user could not be shown", with the seam's Message. Nothing of the user is shown.

A user found has these parts, in this order:

  1. The header: the user's name as its title; in its line, the email when the name is not the email, then "All users", a quiet link back to the list.

  2. A Warn alert, "Changes here leave no audit record", when CanManageAccess or CanConfigure is set and the app's IKitAudit does not record (see Recording changes).

  3. A Neutral alert, "This is your own account", when the user is the viewer: "Another administrator makes changes to it; you cannot change your own access here."

  4. Access (id access). One sentence, the first that applies:

    • "Disabled: cannot sign in until someone enables the account"
    • "Locked out until 17 Nov 2026, 14:20 UTC", or "Locked out until unlocked" for Identity's permanent lock (an end after the year 9000)
    • "No password set: cannot sign in until they choose one"
    • "Can sign in"

    Under it, the facts: the last sign-in (a date, with the time for today and yesterday, or "Never"), the password ("Set" or "Not set") and the email ("Confirmed", "Not confirmed" or "None"). Where the viewer may change the email, the section ends in "Change email", folded.

  5. Two-factor (id two-factor), only when TwoFactorAvailable: "On." or "Off."

  6. Roles (id roles): the role names, or "No role". Where the viewer may change them, the roles form takes the list's place.

Access ends in the email change, when the app allows it and the viewer may make it (see Changing a user's email). Two-factor ends in its reset, when the viewer may reset (see Resetting two-factor). Roles is the roles form when the viewer may change them (see Changing a user's roles). The page shows none of the app's own profile fields; an app adds its own section beside the component. The page writes no log line of its own; the app's seams and the audit seam write theirs (see The app's sessions and notices).

Enabling and disabling a user

The access section ends in the form user-access when all of these hold:

  • CanManageAccess is set.
  • The user was found (Done).
  • The user is not the viewer.

The form posts to the page's own address, its query kept, with #access, so the answer opens at the section. Its first button depends on the user's state:

  • A disabled user: "Enable", a submit (op=enable).
  • An enabled user: "Disable", which opens the confirm user-disable.

Two more buttons follow when they apply (see Ending a lockout and sending a password link).

Both buttons are the Default variant. The confirm's own button, "Disable user", is its one Danger button; no button outside a confirm is Danger. The confirm's text depends on the app's IKitSessions.Ends:

  • True: "They are signed out at once, and cannot sign in until someone enables the account."
  • False: "They cannot sign in until someone enables the account. A session they have open ends within 30 minutes."

How long the session lasts comes from two settings the app configured: Identity's SecurityStampValidatorOptions.ValidationInterval, and the application cookie's options (IdentityConstants.ApplicationScheme). The validator checks a session once the interval has passed since its cookie was issued. The page says the first of these that applies, a span in words ("1 hour 30 minutes"):

Settings The session
An interval of zero or less: Identity validates every request "ends at its next request"
A sliding cookie, the interval more than half its lifetime "is not cut short: it lasts until it expires or they sign out"
A sliding cookie, the interval at most half its lifetime ends within the interval
A cookie that does not slide, the interval at least its lifetime ends within the lifetime, when the cookie expires
A cookie that does not slide, the interval shorter ends within the interval
Cookie options that cannot be read, or name no lifetime ends within the interval

A sliding cookie is reissued once more than half its lifetime has passed. So with Identity's defaults, 30 minutes and a 14-day sliding cookie, the session ends within 30 minutes. With a 7-day interval it ends within 7 days, since the request that reissues it is past the interval too. With an 8-day interval a session in use is reissued before the check comes due, so it is not cut short. A session left idle past the interval is still checked at its next request.

A span of more than 365 days, TimeSpan.MaxValue included, bounds no real session, so it too "is not cut short".

Opening the confirm needs the kit's script, as every confirm does.

Where no form renders, a post to either form answers the framework's 400, and nothing is called. This holds for a viewer without CanManageAccess, for the viewer's own account and for a user out of reach. Each handler acts on the route's UserId alone, never on an id the post carries. The seam's SetEnabledAsync checks reach again.

After a change done (Done), the page does these steps in order:

  1. It calls IKitSessions.EndAsync when the result says EndSessions.
  2. It calls IKitUserNotices.PasswordLinkNeededAsync when the result says NeedsPasswordLink.
  3. It records users.enabled or users.disabled when IKitAudit records. The payload is Enabled, SessionsEnded and PasswordLinkSent.

Each call goes with no cancellation, since the change is not undone. The page then reads the user again and shows one alert at the top of the access section. The alert says what was done, then each clause that applies:

Clause When Tone
"Ada Okoro is enabled" or "Ada Okoro is disabled" Always. Success
"and signed out" The app ended the sessions. Success
"their open session lasts up to 30 minutes" A disable whose sessions the app did not end. Warn
"they have no password; send them a password link" An enable of a user with no password, and the app sent no link. Warn
"they have no password, and were sent a link to set one" The app sent the link. Success
"this change was not recorded" The audit row was not written. The audit seam writes an Error with the action and the user's id. Warn

The alert takes the tone of its most serious clause, for example "Ada Okoro is disabled; their open session lasts up to 30 minutes; this change was not recorded." in Warn. When IKitAudit does not record at all, no row is asked for and the alert adds no clause, since the page's own Warn alert says so.

Other outcomes show other alerts:

  • Unchanged: a Neutral note, such as "Ada Okoro is already disabled; nothing changed." A disable answered Unchanged still calls EndAsync. When it ends the sessions, the note says "and now signed out"; when it does not, the note adds how long the open session lasts. The note stays Neutral, and nothing is recorded.
  • Any refusal: a Danger alert, "Ada Okoro was not disabled", with the seam's Message.
  • An op the form never renders: a Warn alert, and nothing changes.

The user-access form shows two more buttons, under the same conditions as "Enable". Each is a submit of the Default variant, after "Enable" or "Disable":

Button op Shown while
"End lockout" unlock The user is locked out (LockedOutUntil is set), until a time or until unlocked. A lockout by wrong authenticator codes is Identity's lockout end, so the one button ends both kinds.
"Send password link" password-link The user has no password (HasPassword is false). Such a user cannot sign in, and the link sent when the account was made or enabled can be lost.

"End lockout" calls IKitUsers.UnlockAsync for the route's UserId, then reads the user again. It shows one alert at the top of the access section:

Outcome Alert Recorded
Done Success: "Lockout ended for Ada Okoro." users.unlocked, its payload LockedOutUntil, the lockout's end as the page read it.
Done, the row not written Warn: "Lockout ended for Ada Okoro; this change was not recorded." The audit seam writes an Error.
Unchanged Neutral: "Ada Okoro was not locked out; nothing changed." Another administrator ended it first. Nothing.
A refusal Danger, titled "Lockout not ended for Ada Okoro", with the seam's Message. Nothing.

"Send password link" calls IKitUserNotices.PasswordLinkNeededAsync for the user's id, as the lookup for the route answered it, never an id the post carries. It writes nothing to the user, so the page does not read the user again:

Answer Alert Recorded
Sent Success: "Password link sent to Ada Okoro." users.password-link-sent, with an empty payload.
Sent, the row not written Warn: "Password link sent to Ada Okoro; this was not recorded." The audit seam writes an Error.
Not sent: the app registers no IKitUserNotices Warn: "No password link was sent: this app sends none from here. Ada Okoro has no password and cannot sign in until someone sends them a link to set one." Nothing, since nothing was sent.
Not sent: the app's seam answered false, threw, or could not be resolved Warn: "No password link was sent: the app could not send it; its log says why. Ada Okoro has no password and cannot sign in until someone sends them a link to set one." Nothing. A seam that threw writes the guard's Error.
The user has a password by the time the post arrives Neutral: "Ada Okoro has a password now; no link was sent." The seam is not called. Nothing.

An app that registers no IKitUserNotices shows the button and the not-sent alert every time. The alert says why, and the default seam writes its Warning once a process. When IKitAudit does not record at all, neither action asks for a row, and the page's own Warn alert says changes leave no record.

Where no form renders, a post with either op answers the framework's 400 and calls nothing, as for "Enable". An op the form never renders, such as Unlock or password_link, is a Warn alert, and nothing is called.

Resetting two-factor

An administrator resets the two-factor of a user who lost their authenticator. The host needs these, as the framework's AddSolhigsonTwoFactor and TwoFactorManager documentation describes them:

  • AddSolhigsonTwoFactor on the identity registration. Without it, TwoFactorAvailable is false and no confirm renders.
  • Identity's EF UserStore, saving through the app's context with AutoSaveChanges on. Without it, every reset answers Failed, with an Error at step Reset.
  • The counter store AddSolhigsonTwoFactor registers: the framework's Redis store, unless the app registers its own ICounterStore. Building the Redis store needs an IHostEnvironment, which every ASP.NET Core and generic host has. A hand-built container without one fails every reset before anything is written, with the framework's Error at its step TwoFactorCodeCap. With no Redis reachable, a reset still lands. The store answers unavailable and writes its outage's start line once, and the user's code counters are left to run out by themselves.

The two-factor section ends in the confirm user-two-factor-reset when all of these hold:

  • CanManageAccess is set.
  • TwoFactorAvailable is true.
  • The user was found (Done).
  • The user is not the viewer.

The confirm renders whatever the user's state. "Reset two-factor", a Default button, opens it only while the user is enrolled. The confirm posts to the page's own address, its query kept, with #two-factor. Its title is "Reset two-factor for Ada Okoro?", and its own button, "Reset two-factor", is its Danger. Its text depends on the password and on the app's IKitSessions.Ends:

The user Ends The confirm says
Has a password True "Their authenticator and their password are removed, and they are signed out at once. They set a new password from a password link, then enrol again."
Has no password True "Their authenticator is removed, and they are signed out at once. They set a password from a password link, then enrol again."
Has a password False "Their authenticator and their password are removed. They set a new password from a password link, then enrol again. A session they have open ends within 30 minutes."
Has no password False "Their authenticator is removed. They set a password from a password link, then enrol again. A session they have open ends within 30 minutes."

The framework removes the password with the factor, and ends any lockout. How long the session lasts is worked out as for a disable.

The page calls IKitUsers.ResetTwoFactorAsync for the route's UserId, never an id the post carries. The seam checks reach again, and the acting user's id comes from the principal. After a reset done (Done), the page does these steps in order, each with no cancellation:

  1. It calls IKitSessions.EndAsync, since the reset rotated the security stamp.
  2. It calls IKitUserNotices.TwoFactorResetAsync with whether a password was removed. The notice carries the link to set a password, then to enrol again.
  3. It records users.two-factor-reset when IKitAudit records. The payload is PasswordRemoved, SessionsEnded and PasswordLinkSent.

The page then reads the user again and shows one alert at the top of the two-factor section, above its heading. The alert says "Two-factor reset for Ada Okoro", then each clause that applies, in the tone of the most serious:

Clause When Tone
"they are signed out" The app ended the sessions. Success
"their open session lasts up to 30 minutes" The app did not end them. Warn
"they have no password, and were sent a link to set one" The app sent the notice. Success
"they have no password; send them a password link" The app sent none: it registers no IKitUserNotices, or its seam answered false or threw. The user cannot sign in until someone sends the link; "Send password link" on the access section does. Warn
"this change was not recorded" The audit row was not written. Warn

For example: "Two-factor reset for Ada Okoro; they are signed out; they have no password, and were sent a link to set one." in Success.

Every other outcome shows its sentence in one Danger alert at the top of the section, titled "Two-factor not reset for Ada Okoro". Nothing follows: no session ends, no notice is sent and nothing is recorded.

Outcome When
Unchanged (NotEnrolled) The user is not enrolled, such as when another administrator reset them first.
Unchanged (TwoFactorOff) The framework's two-factor is switched off.
NotOwn The user is the acting user's own account, by any form of its id.
A reach refusal, such as NotFound The user is out of reach or gone.
Failed The reset could not be written; the framework's log says why.

Where no confirm renders, a post to it answers the framework's 400 and calls nothing. This holds without CanManageAccess, on a host with no two-factor, for the viewer's own account and for a user out of reach.

Changing a user's roles

The roles section shows the form user-roles in place of the role list when all of these hold:

  • CanConfigure is set.
  • The user was found (Done).
  • The user is not the viewer.

The form posts to the page's own address, its query kept, with #roles. It holds these parts, in order:

  1. One hidden loaded field for each role the user held when the page was rendered.
  2. One fieldset whose legend is "Roles". The legend is for a screen reader; on screen, the section's heading names the group. The fieldset holds a checkbox named role for each role IKitUsers.GrantableRolesAsync offers and each role the user holds, ordered by name, ticked when held.
  3. When RoleChangeDisables is on, the user is enabled and the fieldset holds at least one box, the line "Saving a change disables Ada Okoro until someone enables the account.", in the text colour at the body size, not an alert, directly above the button, which it describes (aria-describedby).
  4. When the fieldset holds at least one box, "Save roles", a submit of the Default variant.

The form offers only what the framework accepts. A grant needs the acting user's grant answer; a revoke needs the reach alone. So a role the user holds that the viewer may not grant is a box like any other, and it can be unticked. Its note says "You cannot grant this role back once it is removed." When GrantableRolesAsync is refused, its sentence shows under the legend, and only the roles held are boxes. A user who holds no role, shown to a viewer who may grant none, shows "There is no role you may grant, and the user holds none." and no button.

The option is the framework's UserAdministrationOptions.RoleChangeDisables, true unless the app sets it:

services.Configure<UserAdministrationOptions>(options => options.RoleChangeDisables = false);

With it on, a role change also disables the user, until anyone who reaches the user enables them. The page reads it through IOptions<UserAdministrationOptions>, as the framework does. The framework registers none, so the default applies until the app configures it.

The page calls IKitUsers.SetRolesAsync for the route's UserId, never an id the post carries, with the boxes ticked and the loaded set as posted. After a change done (Done), the page does these steps in order, each with no cancellation:

  1. It calls IKitSessions.EndAsync, since the change rotated the security stamp.
  2. It calls IKitUserNotices.AccessChangedAsync with the names granted and revoked and whether the user was disabled.
  3. It records users.roles-changed when IKitAudit records. The payload is Granted, Revoked, Disabled, SessionsEnded and NoticeSent.

The page then reads the user again and shows one alert at the top of the roles section. The alert says "Roles saved: added Admin, removed Auditor", naming only what applies, then each clause that applies, in the tone of the most serious:

Clause When Tone
". Ada Okoro is disabled until someone enables the account" The change disabled the user, who stays disabled until someone acts. Warn
"they are signed out" The app ended the sessions. Success
"their open session lasts up to 30 minutes" The app did not end them. Warn
"no notice was sent: this app sends none from here" The app registers no IKitUserNotices. Warn
"no notice was sent: the app could not send it, and its log says why" The app's seam answered false or threw. Warn
"this change was not recorded" The audit row was not written. Warn

For example: "Roles saved: added Admin, removed Auditor. Ada Okoro is disabled until someone enables the account; they are signed out." in Warn. With RoleChangeDisables off and every step followed, the alert is Success: "Roles saved: added Admin, removed Auditor; they are signed out."

Other outcomes:

Outcome The page
Stale A Warn alert at the top of the section: "Roles changed since this page was opened; nothing was saved. The boxes now show the roles Ada Okoro holds." The page reads the user again, so the boxes and the loaded set are as stored.
Unchanged A Neutral note: "Ada Okoro already holds these roles; nothing changed."
Any other Its sentence under the legend, with the boxes ticked as posted and the loaded set as posted. Such as EmptyRoleSet for no box ticked, RoleOutOfReach for a role posted by hand that the viewer may not grant, RoleNotFound, a reach refusal, Failed, and RoleSetRefused, which shows the app's own reason.

Nothing follows a refusal: no session ends, no notice is sent and nothing is recorded. Where no form renders, a post to it answers the framework's 400 and calls nothing. This holds without CanConfigure, for the viewer's own account and for a user out of reach.

Changing a user's email

An administrator changes another user's email here. A user's change of their own email is the app's own flow. The change is off unless the app turns it on, with the framework's UserAdministrationOptions.AllowEmailChange:

services.Configure<UserAdministrationOptions>(options => options.AllowEmailChange = true);

The page and the framework read it through IOptions<UserAdministrationOptions>, so one line turns on both. The access section ends in a native details whose summary is "Change email" when all of these hold:

  • The option is on.
  • CanConfigure is set: an email change is gated with the roles.
  • The user was found (Done).
  • The user is not the viewer.

The details is folded until the administrator opens it. It holds the form user-email, which posts to the page's own address, its query kept, with #access. The form holds one email field, "New email address", empty, then "Change email", a submit of the Default variant. The field's hint says the new address starts unconfirmed. When IKitUsers.SignInNeedsConfirmedEmail is true, the line "They cannot sign in until the app's own flow confirms the new address." sits directly above the button, which it describes (aria-describedby), in the text colour, not an alert.

The page calls IKitUsers.ChangeEmailAsync for the route's UserId, never an id the post carries, with the address as typed. The framework trims it, refuses it or stores it, unconfirmed, and rotates the security stamp. When the user's user name was their address, the user name follows the new address, so they sign in with it. The framework also refuses a user who holds a role the viewer may not grant: reach alone is not enough to move a higher user's address. After a change done (Done), the page does these steps in order, each with no cancellation:

  1. It calls IKitSessions.EndAsync, since the change rotated the security stamp.
  2. It calls IKitUserNotices.EmailChangedAsync with the previous address, so the user hears of it where they read their mail before. A user who had no address is sent no notice, and the alert asks nothing about one.
  3. It records users.email-changed when IKitAudit records. The payload is PreviousEmail, SessionsEnded and NoticeSent. It never holds the new address, which is on the user's row.

The page then reads the user again, folds the details and shows one alert at the top of the access section. The alert says "Email changed for Ada Okoro", by the name read before the change, then each clause that applies, in the tone of the most serious:

Clause When Tone
"they are signed out" The app ended the sessions. Success
"their open session lasts up to 30 minutes" The app did not end them. Warn
"no notice was sent: this app sends none from here; tell them at both addresses" The user had an address, and the app registers no IKitUserNotices. Warn
"no notice was sent: the app could not send it, and its log says why; tell them at both addresses" The user had an address, and the app's seam answered false or threw. Warn
"the new address is not confirmed" Always. Success
"the new address is not confirmed, so they cannot sign in until it is" In place of the clause above, when SignInNeedsConfirmedEmail is true. Warn
"this change was not recorded" The audit row was not written. Warn

For example: "Email changed for Ada Okoro; they are signed out; the new address is not confirmed." in Success.

Other outcomes:

Outcome The page
Unchanged A Neutral note at the top of the section: "Ada Okoro already has this address; nothing changed."
Failed A Danger alert at the top of the section, "Email not changed for Ada Okoro", with the seam's sentence.
Any other Its sentence under the field. Such as InvalidEmail, EmailInUse, RoleOutOfReach ("You may not change this user's email: they hold a role you may not grant."), IdentityFailed, EmailChangeOff and a reach refusal.

Each outcome but Done keeps the address as typed in the field and the details open. Nothing follows: no session ends, no notice is sent and nothing is recorded. Where no form renders, a post to it answers the framework's 400 and calls nothing. This holds with the option off, without CanConfigure, for the viewer's own account and for a user out of reach. Neither address goes in a log line the package writes.

With the option on, one administrator who holds both CanConfigure and CanManageAccess can take over any account within reach whose roles they may grant: move its address to one they read, then send a password link to a user with no password, or reset an enrolled user's two-factor, which removes the password, so the link the app sends reaches the new address. Where the app's own sign-in sends a password reset to an address it has not confirmed, the address change alone is enough, needing CanConfigure only, and giving the two permissions to different roles does not guard it: gate that reset on a confirmed address (an email change leaves the new one unconfirmed), or keep AllowEmailChange off. Otherwise an app guards by giving the two permissions to different roles. Registering IKitUserNotices tells the previous address, after the fact; the audit row users.email-changed keeps it.

The app's sessions and notices

The package defines two seams an app registers for the user screens. AddSolhigsonAdmin registers neither, so register yours before or after it:

services.AddScoped<IKitSessions, AppSessions>();
services.AddScoped<IKitUserNotices, AppUserNotices>();
Seam Member What it does
IKitSessions Ends True when EndAsync signs a user out at once, such as by revoking the user's refresh tokens or server-side sessions. The confirm reads it.
IKitSessions EndAsync(userId, ct) Ends the user's sessions. Answers true when they were ended.
IKitUserNotices PasswordLinkNeededAsync(userId, ct) Sends a user with no password a link to set one. Answers true when it was sent. An enable of such a user, "Send password link" and "Create user" call it.
IKitUserNotices AccessChangedAsync(userId, granted, revoked, disabled, ct) Tells the user their roles changed, by name, and whether the change disabled them. Answers true when it was sent. "Save roles" calls it.
IKitUserNotices TwoFactorResetAsync(userId, hadPassword, ct) Tells the user their two-factor was reset, with a link to set a password, then to enrol again. Answers true when it was sent. "Reset two-factor" calls it.
IKitUserNotices EmailChangedAsync(userId, previousEmail, ct) Tells the user their email changed, at the previous address. Answers true when it was sent. "Change email" calls it.

Without a registration, the package's default answers false: no session ends at once, and no notice is sent. The screens then say what the administrator must do. A seam that throws is caught and counts as false. The page calls each with no cancellation.

The guard writes these lines under Solhigson.Admin.Users.KitUserSeams. A line carries the user's id only, shaped as the users seam's lines shape it, never an email or an exception's message:

Line Level Text What to do
KitUserSeamDefault Warning {Seam} is not registered, so the package's default answers false: {Consequence} Register the app's own. Logged once per process. Register the app's own seam, or accept what the line says follows.
KitUserSeamFailed Error The app's {Seam}.{Member} threw {ExceptionType} for {Action} on user [{UserId}]; it counts as false. Read the app's own log for the exception. IKitAudit.RecordAsync here means the app's audit seam broke its contract, which forbids a throw.

The new-user screen

KitUserCreate creates a user through IKitUsers.CreateAsync. The app writes the page; its route is the users list's CreateHref:

@page "/admin/users/new"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("users.view")]

<KitUserCreate ListHref="~/admin/users" DetailHref="~/admin/users/{id}" CanCreate="@CanCreate" />
Parameter Required What it does
ListHref Yes The users list, a path on this site: the header's "All users" link.
DetailHref Yes A user's page, a path on this site holding {id}, as the list's DetailHref. The new user's id replaces it, url-encoded, before the link goes through KitHref.Local.
CanCreate No Whether the viewer may create users. False unless set. Gate it with the app's own permission check, as CanConfigure on the user page.
ExtraFields No The app's own fields, a RenderFragment<IFormCollection>, rendered after the roles. It is given the app's fields as the form posted them, so it writes back what was typed after a refusal; the form is empty on a first view and after a create.

The header is "New user", with "All users" in its line. Without CanCreate, a Danger alert says the viewer may not create users, and no form renders. With it, the screen reads the roles the viewer may grant (GrantableRolesAsync). A refusal of that read is its Danger alert. No role to grant is an alert that a user must hold one. Neither renders a form. Otherwise the screen holds one form, user-create, which posts to the page's own address, its query kept:

  1. "Email address", required.
  2. "Phone number", a text field with the telephone keypad.
  3. The fieldset "Roles", its legend carrying the required mark, with a box for each role the viewer may grant.
  4. ExtraFields.
  5. "No password is set here; the user chooses one from a password link."
  6. "The user starts disabled, and cannot sign in until someone enables the account.", when the framework's UserAdministrationOptions.NewUserStartsDisabled is on. It is on unless the app turns it off.
  7. "Create user", a Primary submit, which the two lines above describe.

Where no form renders, a post to it answers the framework's 400 and calls nothing.

The page refuses framing, so no other site can lay the form that creates a user under a decoy. The app must send X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on this page, as on the settings page; the framework and the template send neither, and the component sets no header.

The names email, phone, roles and any name starting with _ are the form's own. Name an app field otherwise: a field so named is never given to the app. The framework creates the user with no password and in one transaction with its roles, then reads it back through the rules' Scope. A new user outside the acting user's reach is rolled back and answers NotFound, with its own sentence: "The new user would be outside your reach, so it was not created. If users here belong to a tenant, the app's user factory must set it."

After a create done, the screen does these steps in order, each with no cancellation:

  1. It calls IKitUserNotices.PasswordLinkNeededAsync for the new id.
  2. It records users.created when IKitAudit records. The payload is Roles (the names given, as stored), Disabled and PasswordLinkSent. It never holds the address or the phone, which are on the user's row.

The screen then shows one alert above the form, now empty: "User created", then each clause that applies, in the tone of the most serious, then "Open" and the address, a link to the new user's page:

Clause When Tone
"they are disabled until someone enables the account" The framework started the user disabled. Warn
"they have no password, and were sent a link to set one" The app's seam sent the link. Success
"they have no password, and no link was sent: this app sends none from here; send them a password link" The app registers no IKitUserNotices. Warn
"they have no password, and no link was sent: the app could not send it, and its log says why; send them a password link" The app's seam answered false or threw. Warn
"this change was not recorded" The audit row was not written. Warn

For example: "User created; they have no password, and were sent a link to set one." in Success. An id that holds a literal %2F, with {id} in the address's path, gets no link, as on the users list, since routing would read it as another id: the alert then shows the address alone.

The post handler checks CanCreate and a role to grant itself, before any call, so a path to it that is not the form creates nothing.

Each refusal is said in its place:

Outcome Where
InvalidEmail, EmailInUse Beside the email field.
EmptyRoleSet, RoleNotFound, RoleOutOfReach, RoleSetRefused Under the roles legend, which the fieldset's description names.
The factory's refusal, NotFound, IdentityFailed, NoRules, ActorRefused, Failed A Danger alert above the form, "User not created".

Each keeps the address, the phone and the ticks as posted, and the app's fields through ExtraFields. No link is asked for and nothing is recorded. Neither the address nor the phone goes in a log line the package writes.

Building the new user

The framework creates the user object it is given. IKitUserFactory<TUser> builds it:

public sealed class TenantUserFactory(ITenantContext tenants) : IKitUserFactory<AppUser>
{
    public ValueTask<KitUserBuild<AppUser>> CreateAsync(string email, string? phone, IFormCollection form, CancellationToken ct) =>
        ValueTask.FromResult(form["tenant"] is { Count: > 0 } tenant && tenants.Allows(tenant.ToString())
            ? KitUserBuild.Of(new AppUser(tenant.ToString()) { Email = email, UserName = email, PhoneNumber = phone })
            : KitUserBuild.Refused<AppUser>("Choose the tenant the user belongs to."));
}

services.AddScoped<IKitUserFactory<AppUser>, TenantUserFactory>();

It is given the address and the phone, trimmed (the phone null when blank), and the app's fields, never the form's own. It answers the user, built and not saved, or a sentence the screen shows above the form. The users seam resolves it from the request's services on each create. AddSolhigsonAdmin registers none.

Without one, the package's default builds the user through its public parameterless constructor. It sets the address as the email and the user name, and the phone as the phone number. It reads none of the app's fields. A user type with no public parameterless constructor is refused, with a sentence naming IKitUserFactory<TUser>.

Whichever builds the user, a string id left null or empty is given a new sequential Guid before the create, so a factory need not set one.

An app whose rules scope users by tenant, or by any field of the user's, must register a factory that sets that field. Without it, every new user is outside the acting user's reach, and every create answers NotFound.

The framework then sets the email, trimmed, whether the user is enabled, and clears the password, the lockout, two-factor and a password change asked for. What the factory sets there does not stand. A factory that throws, or answers no build, is Failed, with one Error at step Build.

KitGallery shows every kit component, in every variant and state, on fixed example data, so a look is judged in both themes (its theme choices switch the page) before a screen uses it. Each section is headed by the component's name and the component tokens the manifest names for it; KitShell is shown once, in an inert frame, so its landmarks and skip link never stand beside the page's own. The gallery has no shell of its own, so the app's layout wraps it as any page, and its title is the page's one <h1>. An app cannot be given a route by a component, so the app writes the page that hosts it:

@page "/kit-gallery"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("kit.gallery")]

<KitGallery />

Add it only in development, or behind a permission, as the sample's [Permission] puts it: it shows nothing secret, but it has no purpose in production. An app that wants it in development alone writes that condition in the page in place of the attribute: @inject IWebHostEnvironment Environment, then @if (Environment.IsDevelopment()) { <KitGallery /> }. Every example link and post on it targets the page itself.

KitHref is the one way a kit component takes a url. Blazor encodes an attribute's value but refuses nothing, so javascript:alert(1) or //elsewhere.example written into an href runs or leaves the site. KitHref.Local(value, pathBase) answers a path on this site or null: a path starting with one /, or one starting with ~/, which it joins to the request's path base. It refuses a value holding a control character or white space, and a path part that starts with //, holds a . or .. segment or a backslash, written or percent encoded. KitHref.LocalOrHttps also accepts an absolute https:// address with no user name in it. Each also takes the request itself, KitHref.Local(value, HttpContext) and KitHref.LocalOrHttps(value, HttpContext), and reads its path base. KitHref.LocalOrThrow(value, HttpContext, owner) answers as Local does, or throws naming owner and ending with KitHref.MustPost, "it must post", for a form's action; LocalOrThrow(value, HttpContext, owner, must) ends with must, such as KitHref.MustLink, "it must be a link on this site", for a link a component cannot do without.

A stored menu url starts with ~/, which a Razor component does not resolve. Hand it to KitButton.Href as stored, or resolve it for a link of the app's own with the request's path base, and leave the link out when the answer is null:

@code {
    [CascadingParameter] private HttpContext? HttpContext { get; set; }

    private string? Target(string stored) => KitHref.Local(stored, HttpContext);
}

Light and dark

A page follows the viewer's system theme until the viewer picks one. KitThemeSwitch (Solhigson.Admin.Components) renders the choice, Light, Dark or System, as three ghost buttons in one group, the current one aria-pressed="true". A click switches the page at once, with no round trip: kit.theme.js sets data-theme on the <html> element and keeps the choice a year in the cookie kit-theme (Path=/, SameSite=Lax, Secure on an https page), or, for System, removes data-theme and deletes the cookie.

The server renders the choice, so the first paint is already right. KitTheme.Current(HttpContext) (Solhigson.Admin.Theme) reads the cookie as exactly light or dark, and anything else as no choice; the cookie's text never reaches the page. A component cannot set attributes on the app's <html>, so the app splats KitTheme.HtmlAttributes on it, in its root component:

@using Solhigson.Admin.Theme

<html lang="en" @attributes="KitTheme.HtmlAttributes(HttpContext)">
    <head>
        <KitHead Nonce="@nonce" />
    </head>
    <body>
        <Routes />
    </body>
</html>

@code {
    [CascadingParameter] private HttpContext? HttpContext { get; set; }
}

data-theme on <html> is the kit's attribute: the switch, its script and the stylesheet read and write it. An app that sets its own data-theme there fights the switch; an app that wants a fixed theme sets the tokens instead (see Overriding the kit). After an enhanced navigation, and when the browser shows a page again from its back-forward cache, the script puts the page back in line with the cookie. A page rendered from the cookie differs from one viewer to the next, so it must not sit in a shared cache without Vary: Cookie.

The mark

KitMark renders the package's name and exact version. It belongs on signed-in pages, never an anonymous one: an exact version tells a scanner which advisories apply.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
10.4.0 0 11/20/2026
10.3.0 40 11/19/2026
10.2.0 48 11/18/2026
10.1.0 51 11/17/2026
10.0.0 57 11/16/2026

10.2.0: the user screens (Solhigson.Admin.Components, Solhigson.Admin.Users, Solhigson.Admin.Auditing). The users list: KitUsersList, which an app places on its own page with DetailHref (holding {id}), an optional CreateHref and a TimeZone, lists the users within the signed-in user's reach a page at a time: the name linking to the user's page with the email under it, the roles, the status (Disabled a Neutral pill, Locked out a Warn pill, No password plain text), two-factor and the last sign-in; GET filters by role, status, two-factor, no password and not signed in for 30, 90 or 180 days; and a posted search over email and user name whose text never reaches a link, a form's action, a header or the address. The user page: KitUserDetail, on a page with the user's id in its route, taking UserId, ListHref, TimeZone, CanManageAccess and CanConfigure, says first whether the user can sign in and why not, then shows Access, Two-factor (when the app registers it) and Roles; a user missing and one out of reach both answer 404, and the page must not stream. Its actions each act on the route's id alone, are refused for the viewer's own account and without their permission (a post then gets 400), are recorded through IKitAudit, and say in one alert what was done and what did not follow: with CanManageAccess, Enable, and Disable after a KitConfirm; End lockout; Send password link, for a user with no password; and Reset two-factor after a KitConfirm, which removes the authenticator and the password; with CanConfigure, the roles form, offering the roles the viewer may grant and those held, refused as stale when the roles changed since the page loaded, and saying when RoleChangeDisables makes a save disable the user; and, where the app turns on UserAdministrationOptions.AllowEmailChange, Change email, refused for a user who holds a role the viewer may not grant, the new address starting unconfirmed. User creation: KitUserCreate, with ListHref, DetailHref, CanCreate and an optional ExtraFields fragment for the app's own fields, creates a user with an email, a phone and the roles the viewer may grant, with no password and disabled while NewUserStartsDisabled is on, and asks for a password link; the user is built by the app's IKitUserFactory<TUser> (KitUserBuild.Of or KitUserBuild.Refused), else through the user type's public parameterless constructor, and an app whose rules scope users by tenant must register a factory that sets it, or every create answers NotFound. The seams: IKitUsers, which AddSolhigsonAdmin registers scoped over the framework's UserAdministration, is how the screens read and change users (SearchAsync, GetAsync, GrantableRolesAsync, RoleNamesAsync, SetEnabledAsync, UnlockAsync, ResetTwoFactorAsync, SetRolesAsync, ChangeEmailAsync, CreateAsync, TwoFactorAvailable, SignInNeedsConfirmedEmail; with KitUserSearch, KitUserPage, KitUserLookup, KitUserRow, KitRoleNames, KitUserResult, KitNewUser, KitUserMessages and KitUserAudit's users.* actions), and throws nothing but the caller's cancellation; IKitSessions (Ends, EndAsync) and IKitUserNotices (PasswordLinkNeededAsync, AccessChangedAsync, TwoFactorResetAsync, EmailChangedAsync), which an app registers to end sessions in its own store and to send the link and the notices, and whose defaults answer false and warn once a process, so the screens tell the administrator what to send and how long an open session lasts, read from the security stamp validation interval and the application cookie; and IKitUserFactory<TUser>. One rule names the acting user for the users seam and the audit seam alike: the first claim of Identity's ClaimsIdentity.UserIdClaimType, counted only from a signed-in identity. Changes for a 10.1.0 app: the audit seam's actor, when the actor provider gives the unattributed one, now follows that rule, so the sub fallback is gone and an app whose tokens carry the id as sub sets UserIdClaimType to sub; AddSolhigsonAdmin now also registers IKitUsers, so it registers IKitMenuSource, IKitAudit, IHttpContextAccessor and IKitUsers, each kept when the app registered it first; KitAuditEvent's payload holds no personal value but users.email-changed's previous address; and KitAuditFailed names the exception's type only, never its message. KitHref.LocalOrThrow gains an overload taking what the value must be (KitHref.MustPost, KitHref.MustLink), KitPageHeader gains LineContent, KitFilterBar gains Id, and kit.manifest.json gains the kit-user and kit-users names. The README lists each log line the screens and seams write, its level and what to do, beside the framework's user_administration and two_factor counters on the meter Solhigson.Framework.Identity. The user pages refuse framing, as the settings page does: the app sends X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on them, and the components set no header. With AllowEmailChange on, one administrator holding both CanConfigure and CanManageAccess can take over any account within reach whose roles they may grant: move its address, then send a password link or reset its two-factor. Where the app's own sign-in sends a password reset to an address it has not confirmed, the address change alone is enough, needing CanConfigure only, and giving the two permissions to different roles does not guard it: gate that reset on a confirmed address (an email change leaves the new one unconfirmed), or keep AllowEmailChange off. Otherwise an app guards by giving the two permissions to different roles. Registering IKitUserNotices tells the previous address, after the fact. Minor bump: every type and member is new but for those four changes. Depends on Solhigson.Framework.Core 10.27.0 or later. 10.1.0: the settings screen, the package's first screen (Solhigson.Admin.Components, Solhigson.Admin.Settings, Solhigson.Admin.Auditing). KitSettingsEditor, which an app places on a page of its own with its route and [Permission], lists every setting the app's catalogue declares, one section a group in the order the catalogue registered them, under a Settings header that counts them and links to a needs-attention view, with a GET filter over key, name and purpose, never a value. CanEdit, false unless set, comes from a second permission: without it no form renders, a post is the framework's 400 and a Personal value shows as Hidden; a Secret's value is never written into the page. With it each line is a form of its own that saves or resets that setting through Core's SaveDeclaredSettingAsync and ResetDeclaredSettingAsync and says the outcome at the line: saved, reset, no change, a refusal beside the field in the screen's words with what was typed kept (never a secret's), changed since the page loaded, failed with no exception text, and a Warn alert when other instances were not told and may show the old value until their settings cache recovers. Under the groups, Rows with no declaration lists each stored row no declared setting matches, by name and flag pills, never a value; with CanEdit each has a Remove that opens one KitConfirm saying older code may still read the row by name and the screen cannot put it back, and its confirm calls RemoveUndeclaredRowAsync. Above the groups a warning says a secret's save is refused while the legacy encryptor is in force. The setting field: KitSettingField renders one KitSetting (KitSetting.From(DeclaredSettingLine)) with one control of its kind: a Switch a toggle that submits its form when it changes (a Save in noscript otherwise), a number with min, max and step, a Duration an amount and a unit or one text field, a List a textarea, a Text a text field; a Secret, a row stored sensitive and a masked line an empty password field, with no value or mask in the markup; with ReadOnly, Fields, Error and ChildContent. KitSettingValue.Compose turns the posted KitSettingFields into the setting's stored text or a refusal sentence (KitSettingComposed), never an exception, and Fill gives each control's starting values. The audit seam: IKitAudit (Records, and RecordAsync answering whether a row was written), which AddSolhigsonAdmin registers scoped as KitAudit<TContext>, resolving the audit service, the actor provider and the context from the request at first use; KitAuditEvent and KitAuditActions. Each save, reset and removal done is recorded as a SecurityEvent on AppSetting, settings.saved, settings.reset or settings.stray-removed, with the actor and a payload of the key and the values before and after as the framework's result shows them, the mask for a Secret, a row stored sensitive and a Personal value. A removed stray row stored plain under a plain name keeps its raw value in the append-only audit row: only a row stored sensitive or under a secret-looking name is masked. When Records is false (no audit service resolves, or the context maps no AuditTrail and no IAuditSink is registered) the screen says changes here leave no audit record and one Warning is logged a process; a record that fails logs one Error and says so at the line, and the change is not undone. TContext must be registered scoped. KitConfirm gains OnConfirm and KitDialog OnSubmit, so a confirm's form is handled by the component that owns it; kit.forms.js submits the form of a data-kit-submit-on-change control and keeps one such post in flight a page; the gallery gains a settings section; kit.manifest.json gains the kit-setting and kit-settings names. The README documents the app's page and every log line the screen, the seam and a save write. Minor bump: every type and member is new, and no existing component's behaviour changes. Depends on Solhigson.Framework.Core 10.27.0 or later. 10.0.0: the first release of Solhigson.Admin, the admin kit: Razor components for Solhigson apps, rendered statically on the server, with no interactive render mode and no inline script; an app owns every route, and the package holds components and no screen yet. Head and theme: KitHead, first in <head>, links the kit's stylesheet and scripts with the page's nonce where its policy uses one; KitTheme reads the viewer's light or dark choice from its cookie on the server, with KitTheme.HtmlAttributes(HttpContext) for <html>, and KitThemeSwitch offers the choice. Components: KitButton, KitStatusPill and KitAlert; KitField, one field for every input kind; KitDialog (a modal or a drawer) and KitConfirm on the native <dialog>; KitMenu, KitMenuItem and KitMenuForm, a row menu on the native popover; KitShell, the admin layout with a skip link, a side rail, a top bar with the user's menu (the theme choices and sign-out) and the main region; KitPageHeader, KitLead, KitEmptyState and KitPager; KitTable with KitColumn, and KitFilterBar, Get or Post; KitMark; and KitGallery, every component in every state on fixed example data, for a page an app adds in development or behind a permission. Links: every url a kit component takes goes through KitHref: a ~/ path is joined to the path base; a button's or a link menu item's Href may also be an https:// address (KitHref.LocalOrHttps), and a form's action is local alone (KitHref.Local). Menu: IKitMenuSource builds the shell's menu from the permissions the signed-in user's roles hold, read through PermissionManager's cached reads, and AddSolhigsonAdmin<TUser, TContext>() or AddSolhigsonAdmin<TUser, TKey, TContext>() registers it; the menu shows, each page's [Permission] enforces. Styles: tokens for every colour, size, space, radius, shadow, duration, curve and font, light and dark, in layers (kit.tokens, kit.base, kit.components) that an app's app layer overrides, each name listed in kit.manifest.json, a name leaving which is a breaking change; every motion reads a duration token that is 0ms under prefers-reduced-motion. Rules: the package's tests hold its markup, scripts and stylesheets to no inline script, style or handler, no other host, every href and form action through KitHref, measured contrast pairs, and no colour, length or duration outside the tokens. Depends on Solhigson.Framework.Core 10.24.0 or later.