Solhigson.Admin
10.4.0
dotnet add package Solhigson.Admin --version 10.4.0
NuGet\Install-Package Solhigson.Admin -Version 10.4.0
<PackageReference Include="Solhigson.Admin" Version="10.4.0" />
<PackageVersion Include="Solhigson.Admin" Version="10.4.0" />
<PackageReference Include="Solhigson.Admin" />
paket add Solhigson.Admin --version 10.4.0
#r "nuget: Solhigson.Admin, 10.4.0"
#:package Solhigson.Admin@10.4.0
#addin nuget:?package=Solhigson.Admin&version=10.4.0
#tool nuget:?package=Solhigson.Admin&version=10.4.0
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: first kit.core.js, which hands Blazor what
kit.notice.js and kit.nav.js run after each enhanced navigation (kit.forms.js, kit.theme.js and kit.menu.js
hand their own); 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; kit.menu.js, which places the row menus under Row menus;
kit.notice.js, which tells a screen reader what a notice says under Notices; and kit.nav.js, which moves
a page changed to in from the side it came from under The admin shell.
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:
- 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-inksets--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-dangersets--kit-state-danger-hoverlikewise. The focus ring is black (white in dark) and stays so: an app re-inking the kit decides--kit-focusitself. - A component token, such as
--kit-mark-gapor--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:rootor on the component. The one exception is--kit-btn-busy-width, whichkit.forms.jssets on a busy button to the width it had, and which an app does not set. - 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), or --kit-d-theme, the fade of a theme change, whose class --kit-d-theme-hold keeps on the page a
little longer (see Light and dark), or --kit-d-enter, a page change coming in, or --kit-d-glide,
the rail's marker gliding to the current item (both in The admin shell), or a busy button's
--kit-d-dots, one pulse of a working dot, and --kit-d-dots-step, the step by which each dot follows the one before
(see Buttons), or a button's answer, --kit-d-flash, its landed ring, and --kit-d-nudge, its failed
nudge (also in Buttons), or a notice's --kit-d-notice, its rise, and --kit-d-notice-leave, its leave
(see Notices). 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 or --kit-<component>-<name>-dwell, is a wait, not a motion: it keeps its time, so a notice
still leaves after --kit-notice-dwell, and a busy button still frees its form after --kit-btn-busy-dwell.
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. An app that overrides --kit-d-theme keeps
--kit-d-theme-hold at least as long, so the fade's class stays until its colours have landed, and repeats both as
0ms under prefers-reduced-motion. Each theme token is a time such as 320ms or 0.32s, or a var() to one: the
script reads it as the browser hands it over, so a calc() is not read and the theme swaps at once.
@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.
A submit button given BusyText, the word it reads while its post is out, shows that word and three working dots in
place of its label while it is busy, in its own text colour; the dots pulse in turn, and stand still under
prefers-reduced-motion. The word is the app's to write, since a doing word cannot be made from every label in every
language. The button lays its label over the word and the dots, which are hidden until it is busy, so the wider of
the two sets its width at rest and busy alike, and nothing beside it moves when it is marked. The label turns
transparent in place, so a screen reader still names the button by it; the word and the dots are hidden from a
screen reader. kit.forms.js also sets --kit-btn-busy-width on the button as it marks it, the width it had, which
the busy button holds; a property set in script, so no style attribute reaches the markup. A link takes no word.
<KitButton Variant="KitButtonVariant.Primary" Type="submit" BusyText="Saving">Save</KitButton>
While a form's button is busy, a second submit of that form is not sent: kit.forms.js cancels it in the capture
phase, before Blazor's own submit listener, which sends nothing for a cancelled submit. Another form submits as
usual, and so does a dialog's close or cancel (formmethod="dialog"), which opens no page. Each of the form's
submit buttons, one outside it that names it with form among them, is marked data-kit-held while the form is
held, and shows the progress cursor and neither lights nor moves; a dialog's or a disabled one keeps its own look. A
script that cancels an enhanced kit form's submit and sends it again with requestSubmit is cancelled too, until
the mark clears; form.submit(), which fires no submit event, or a form that is not enhanced, is its way out. This
spares a second click and nothing more: a second tab, or a replay of the same post, still reaches the server, so the
server's own answers stay the bar against a post sent twice.
The mark, its width, the guard and data-kit-held clear together: on enhancedload, on pageshow, and after
--kit-btn-busy-dwell (20s) when neither came. A post whose fetch failed, or one answered by a file or by no page,
brings neither event, so only the dwell frees its form; the label then returns and the user can send it again. The
20s is a wait the kit chose, longer than a form post should take and short enough that a failed one is soon free
again; no host time limit sets it. A post slower than the dwell can be sent again by a second click after it, which
the server's answers still judge. An app whose posts take longer sets a longer --kit-btn-busy-dwell on :root.
Answer (KitButtonAnswer) draws a post's answer on the button, on the render that answers it. Landed adds
kit-btn-landed: a box-shadow ring in --kit-state-success spreads from the button's edge to --kit-flash-spread
(10px) and fades over --kit-d-flash (700ms) on --kit-ease. Failed adds kit-btn-nudged: the button moves
sideways (translateX) through --kit-nudge-1, --kit-nudge-2 and --kit-nudge-3 (-5px, 4px, -2px) and back to 0
over --kit-d-nudge (300ms) on --kit-ease. None, the default, draws nothing. Each plays once and leaves nothing
behind, and neither changes the button's colour, text or size, so the answer is said in words, in an alert or a
notice, and never by the ring or the nudge alone. Under prefers-reduced-motion neither moves. Any KitButton takes
Answer, so a post made from a KitConfirm answers on a KitButton that opened it; a row menu's item takes no
answer. The two ring shadows, --kit-flash-ring and --kit-flash-ring-end, read --kit-flash-spread on :root, so
an app that changes the spread sets it there.
<form method="post" @formname="save-row" @onsubmit="SaveAsync">
<AntiforgeryToken />
@if (answer == KitButtonAnswer.Landed)
{
<KitAlert Tone="KitTone.Success"><p>The row is saved.</p></KitAlert>
}
else if (answer == KitButtonAnswer.Failed)
{
<KitAlert Tone="KitTone.Danger" Title="Not saved"><p>The row changed since you opened it. Reload it and save again.</p></KitAlert>
}
<KitButton Variant="KitButtonVariant.Primary" Type="submit" BusyText="Saving" Answer="@answer">Save</KitButton>
</form>
@code {
private KitButtonAnswer answer;
private async Task SaveAsync()
{
var saved = await SaveTheRowAsync();
answer = saved ? KitButtonAnswer.Landed : KitButtonAnswer.Failed;
}
}
Where a page draws KitNotice for a landed post, the button takes no Landed, so one answer is one motion: the ring
is for a form that draws no KitNotice; the page still says the answer in a KitAlert or the shell's Messages. A
static page sets Answer on the render that answers the post alone, as the field above does, None on every other
request. A page that sets it on every render, from a stored outcome or a query value, rings or nudges the button on a
plain reload too, and on any later visit to the page.
A post answered on the same path keeps the button element, so a class it still had would not play again:
kit.forms.js, as it marks a post's submitter busy, takes kit-btn-landed and kit-btn-nudged off every element on
the page, the submitter and a confirm's opener among them, and the next answer's class plays. As with a notice, an
answer replays only after a post a kit button or a KitSettingField sends.
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>
Notices
KitNotice says a post's answer in one message at the foot of the screen, which rises in, stays long enough to read and
leaves on its own. Its Message is a KitNoticeMessage: KitNoticeMessage.Landed(text) for a post that landed, or
KitNoticeMessage.NotLanded(text, step) for one that did not, where step is one sentence saying what to do next, so a
failure never says only that it failed. An empty or blank text or step throws ArgumentException. With no Message the
notice renders nothing. The shell's Messages stay for what lasts on the page; a notice is the moment the answer
arrives.
<KitNotice Message="@notice" />
@code {
private KitNoticeMessage? notice = KitNoticeMessage.NotLanded("The invitation was not sent.", "Check the email address and send it again.");
}
A notice is the raised surface, --kit-surface-raised, in --kit-fg text, edged by --kit-line under
--kit-shadow-menu. Its mark is a field error's in shape, a glyph in a filled disc: a landed notice shows a check on
--kit-state-success in --kit-on-state-success; one that did not land shows a ! on --kit-state-danger in
--kit-on-state-danger, and its step as a second, smaller line. Each mark has a text alternative, LandedText
(Done:) and NotLandedText (Not done:). It is fixed above the viewport's foot, centred inside the page gutter, at
most --kit-measure wide, at the floating layer --kit-z-float, above the skip link's --kit-z-skip. A word too long
for its line, an address or a name, breaks anywhere, so a notice never passes a phone's screen.
It moves by CSS alone. It rises from --kit-notice-rise (12px) below over --kit-d-notice (280ms) on --kit-ease,
stays --kit-notice-dwell (2800ms), or --kit-notice-long-dwell (4200ms) when the post did not land, then leaves over
--kit-d-notice-leave (220ms) on --kit-ease-leave, ending hidden (visibility: hidden) with no pointer events. A
pointer over it pauses its stay and its leave until the pointer goes; its rise plays on, so a pointer resting where the
notice appears does not hold it half risen. Under prefers-reduced-motion both durations are 0ms and the dwells keep
their time, so the notice shows at once, stays, and goes at once.
A post answered on the same path keeps every element whose tag matches, so a notice left in place would not play again:
kit.forms.js removes every .kit-notice element as it marks a post's submitter busy (see Buttons), and
the answer's notice, a new element, plays, even when it says the same words. A notice replays only after a post a kit
button or a KitSettingField sends, since kit.forms.js marks no other submitter busy: the answer to a post any other
control sends on the same path keeps the notice element in place, so it does not play again.
The notice itself is hidden from assistive technology (aria-hidden="true"). KitShell renders after its <main> two
live regions, role="status" and role="alert", empty and present on every page, since a region inserted already
holding its text is announced unreliably. kit.notice.js, at start and on each enhancedload, writes the page's first
notice outside an inert element, its mark's alternative, its text and its step, by textContent into the status region
for a landed notice or the alert region for one that did not land, and empties the other; a page with no notice empties
both. A notice already told with the same words is not told again. A KitNotice outside KitShell renders nothing,
since no region there can tell it: the shell gives its page the cascading value a notice renders under. Without script a
notice is drawn and not announced.
A position: fixed element is placed against an ancestor that has a transform, not the viewport. The shell's main
region has one only while a page change plays (see The admin shell): a post answered by a page on
another path plays the page change, and unless the change is the fade alone, for --kit-d-enter (240ms) the notice is
placed against <main>, off the screen on a page longer than the window, and then lands at the viewport's foot, most of
its rise played. A notice inside an element an app's own rule transforms moves with that element.
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 byforandid; the hint and the error describe it byaria-describedby. - An
Errormarks the controlaria-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. Requiredputsrequiredon the control and a visible mark in the label, read as "(required)".- The id is
kit-field-and theName, every character that is not an ASCII letter or digit written as_and its four hex digits (Items[0].Nameiskit-field-Items_005B0_005D_002EName). It is the same on every render and different for every other name. Two fields of oneNameon one page, in two forms, each need their ownId. - A
Passwordnever writesValueinto the page, so a stored secret shows only as set or not set; it carriesautocomplete="new-password"unlessAutoCompletesays otherwise, since browsers ignoreoffon a password and would fill the administrator's own saved password. - A
Selecttakes itsOptionsas value and text pairs, in order; the option whose value equalsValue, compared ordinally, is selected.Placeholderadds a first, empty option, chosen whenValueis empty. Min,MaxandStepare aNumber's or aDate's;ReadOnlyis an input's or a textarea's, since a browser lets a select, a checkbox and a toggle change though they are read-only (useDisabled). A parameter the kind cannot honour is refused with an exception, as areOptionson any kind but aSelect.- Every other attribute lands on the control. The field owns
id,name,required,disabledandaria-invalidon every control;type,value,placeholder,min,max,step,readonlyandautocompleteon an input;placeholder,readonlyandautocompleteon a textarea;autocompleteon a select;type,valueandcheckedon a box or a toggle; androleon a toggle. It writes them after the caller's, so a passed one is replaced; set them through the parameters. A passedclassand a passedaria-describedbyjoin the field's own. A url attribute is refused, asKitButtonrefuses 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,
HrefthroughKitHref.LocalOrHttps; - a dialog opener,
OpenDialognaming aKitDialogorKitConfirm, with itsdata-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
KitMenuFormof itsFormName(form=) to its ownAction(formaction=, throughKitHref.Local), with thenameandvaluewritten on the item: the pressed row's value alone is posted; - a theme choice,
ThemeChoicelight,darkorsystem, arole="menuitemradio"thatkit.theme.jsswitches as it switches aKitThemeSwitchchoice,aria-checkedon 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, and after it two empty live
regions a notice is announced in (see Notices). 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 an ink fill, or
where the rail's line is drawn (below) by weight and the line. 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.
In a browser that can anchor one element to another and scope the anchor's name (CSS anchor positioning with
anchor-scope), the rail draws a line in the ink, --kit-rail-marker-line (3px), at the current item's start edge, and
the current item keeps its weight and drops its soft fill, so the line and the weight mark it. After an enhanced
navigation, which keeps the rail and moves aria-current, the line glides to the item picked over --kit-d-glide
(340ms) on --kit-ease; a full load draws it in place. The line follows its item on any other move too: a group opened
or closed above it, or the window resized across 720px, glides it. At 720px and under, where the rail is a row, the line
lies under the item. While a group holding the current item is closed, the line sits at its summary. Each rail scopes
its anchor (anchor-scope), so a second shell on the page anchors its own line. The line is the rail's last element, an
empty span.kit-rail-marker hidden from assistive technology, so aria-current alone tells a reader the current item.
A page with no current item draws no line. A browser without anchor positioning or anchor-scope lays out no line,
since the stylesheet makes the span no box there, and the current item keeps its fill. The span carries no hidden
attribute, so an app's reset such as [hidden] { display: none !important; } cannot hide the line. In forced colours,
where fills are not drawn, the line is the system's text colour (CanvasText). Under prefers-reduced-motion
--kit-d-glide is 0ms, so the line jumps.
A page change moves with its direction. After an enhanced navigation to another path, kit.nav.js fades the main
region in over --kit-d-enter (240ms) on --kit-ease as it moves in from the side the page came from. A deeper page,
one with more path segments past the path of document.baseURI (an app's path base), is pushed in from the right by
--kit-enter-push (48px), and a shallower one from the left; where the main region's direction is rtl the two
swap. A page at the same depth drifts in by --kit-enter-drift (22px) toward the rail item picked, along the rail:
the shell renders data-kit-main on its <main> and data-kit-nav-index, its place in Menu, on each top-level
rail item. Beside the rail's column, a current item further down the menu than the last page's brings the page up
from below, one further up brings it down from above; at 720px wide and under, where the rail is a row, the page comes
from the inline end or the start, mirrored under rtl. Where either page has no current item, the page fades in
alone. The page left is not drawn leaving, since enhanced navigation has already replaced it.
A post answered on the same path, a change of the query alone (a filter, a pager's cursor), the first page and a full
load move nothing, and so does a change to or from a page with no shell (an app's own sign-in page outside
KitShell). A streamed update or a post answered in place while a move still plays leaves the move playing from where
it was, even when an app's own enhancedload listener reads the layout first. A streaming layout whose first chunk
renders no shell <main> gets no move on that navigation, since the move is chosen when that chunk is on the page.
Under prefers-reduced-motion --kit-d-enter is 0ms, so nothing moves. Where an app's own rule sets the main
region's animation, the move's classes come straight off and nothing moves.
While the page slides sideways or up the shell's body clips what passes its edge, so no scrollbar comes and goes; a
page wider than the shell's body, a wide table the page scrolls sideways, loses its sideways scrollbar and is cut at
the body's edge for the move's 240ms. The main region keeps no transform once it has come in, so a position: fixed
element an app puts inside it is placed against the viewport again after the move.
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,
all scoped, the menu source, the users seam (see Users), the roles seam (see Roles), the audit
seam (see Recording changes) and the audit reader seam (see
Reading the audit trail). It also registers IHttpContextAccessor, which the audit seam
reads the signed-in user through, and TimeProvider.System when the app registers no TimeProvider, 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. Enhance is true
unless set. A bar holding a field named after a member of the form element, such as action, method or target,
sets it false and then submits as a plain form, loading the page whole: the browser reads that field in place of the
form's own member, so Blazor's enhanced submit, which reads the form's action, would fetch a wrong address. The
audit screen's bar is such a bar. 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" HistoryHref="~/admin/audit" />
}
@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.
HistoryHref, null unless set, is the audit page's path on this site, alone, with no query or fragment: the page of
The audit screen, ~/admin/audit in the sample. With it, each row's control column ends with
"History", a Ghost button link to that page at ?type=AppSetting&id=<key>, each value escaped with
Uri.EscapeDataString and the link passed through KitHref.Local. It names no day, so the list reads the setting's
whole history. A visually hidden "of" and the setting's label follow the word, so each row's link names its setting by
its label. A setting's history lists the changes made on the settings screen, by the type AppSetting and the setting's
key; it does not list the rows audit capture may write for the AppSetting table under the row's numeric id. Without
HistoryHref no link renders; a value that is no path on this site, or that holds a query or a fragment, throws when
the page renders.
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.resetorsettings.stray-removed(KitAuditActions); - the entity type
AppSetting(KitAuditEvent.SettingEntityType), 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,
PreviousShownandNewShown, 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'sNewShownis null, and itsPreviousShownis 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:
IKitAuditis not registered;- no audit service resolves;
- the app's context does not map
AuditTrailand noIAuditSinkis 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.
Recordsis false when no audit service resolves, or when the context does not mapAuditTrailand noIAuditSinkis 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 asksRecordsto say on the page that its changes are not recorded. An app that never calledAddSolhigsonAdmingets a seam whoseRecordsis 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.
KitAuditEventcarries 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 isweb. Its id is read as the users seam reads the acting user (see The acting user): the first claim of Identity'sClaimsIdentity.UserIdClaimType(NameIdentifierunless 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 assubsetsUserIdClaimTypetosub. 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. |
Reading the audit trail
IKitAuditReader (Solhigson.Admin.Auditing) is the one seam through which an admin screen reads the audit trail.
AddSolhigsonAdmin registers it, scoped, as KitAuditReader<TContext> over the framework's
IAuditTrailReader<TContext> for the app's identity context, with either overload. A seam the app registered first is
kept. The framework registers its reader through Autofac, open-generic, so the seam resolves the reader and the context
from the request's services at first use. AddSolhigsonAdmin also registers TimeProvider.System when the app
registers no TimeProvider; the seam reads the time from it.
| Member | Answers | What it reads |
|---|---|---|
Available |
bool |
False when no reader resolves, when the context does not map AuditTrail, or when resolving the reader or the context threw. It is decided once a request, at the first use of Available or of a signed-in viewer's read; a refused read resolves nothing. A throw writes one KitAuditReaderUnresolved, naming the first member that resolved the reader, and is not tried again in the request. When false, every read of a signed-in viewer answers NotAvailable and queries nothing. Available never throws. |
SearchAsync(principal, search, ct) |
KitAuditPage (Rows, NextCursor, From, To, Offset, ReadAt, Scoped, NamesUnavailable, Outcome, Message) |
One page of the framework's SearchAsync, newest first, at the reader's default page size. Every filter and the cursor in search are passed through. The page says the window, the offset, the instant the time was read at and the scope it read. |
GetAsync(principal, id, createdKey, ct) |
KitAuditLookup (Record, Outcome, Message) |
The framework's GetAsync of one row. id is the row's id in its "D" form and createdKey is the row's CreatedKey. An id that is not a Guid in that form, a key AuditTrailKey.TryParseCreatedKey refuses, and a key that matches no row all answer NotFound. The first two read nothing. |
A KitAuditSearch holds FromDay, ToDay, Category, Action, EntityType, EntityId, ActorUserId, Cursor
and Zone. Each string filter narrows by exact equality when it is not blank. The days are the viewer's days in
Zone, the last one searched whole; a null zone is UTC.
The window is the framework's AuditTrailWindow.Resolve:
- The time is read once. The offset is
Zone.GetUtcOffsetat that time, so a zone in its summer gives its summer offset. With no zone, the offset is zero. - With no days, a search naming an entity type, an entity id or an actor is scoped (
AuditTrailSearch.IsScoped). It reads all time, from 1 January 2000 to the midnight after today in UTC. - Any other search with no days reads the viewer's today at the offset.
FromandToon the page are UTC instants;Offsetis the offset used.
A KitAuditRow holds Id, CreatedKey, Created (UTC), Category, Action, ActionLabel, Subject, Actor,
EntityType, EntityId, ActorUserId, Linkable, ActorLinkable and ActorAttempted. ActionLabel is
KitAuditLabels.For (below). Subject and Actor are the framework's AuditDisplay labels, built from the names
stored on the row or, where it stores none, the names looked up for the viewer (below).
Linkable says whether a link may carry the row's entity id. It is true for a DataChange, whose id is an entity's
key, and for an action the package records, compared exactly as stored: the settings screen's (KitAuditActions), the
user screens' (KitUserAudit) and the role screens' (KitRoleAudit). It is false for every other row, such as a
sign-in event, whose entity id may be text a caller typed.
ActorLinkable says whether a link may carry the row's ActorUserId: the id is stored and is a user's key, on a
Linkable row or on a row whose actor the viewer's name lookup named. A sign-in event's actor id may be text a caller
typed too. ActorAttempted says the row stores an actor's name and no actor id, on a SecurityEvent that is not
Linkable, the name not the framework's AuditActor.Unattributed: the identity a caller gave, never a person the
trail knows.
A KitAuditRecord is a row with Sentence, SourceType, SourceId, UserIp, Changes and Snapshot read by the
framework's AuditPayload, and Restricted and NamesUnavailable (below). Sentence is KitAuditLabels.Sentence
of the record's category, action, entity type, Actor and Subject. It is worked out each time it is read, so a copy
of the record with other names reads with those names. The seam's types give a log their key, their outcome or the
names of the filters set, never a value.
The people on a row
A name a row stores shows to every viewer. An id a row stores with no name is looked up through the framework's
UserAdministration.ResolveDisplayNamesAsync, for the viewer, in one call a page or a record:
- An actor id is looked up when the row stores no actor name.
- A subject id is looked up only when the row stores no subject name, its entity type is a user's and its action is
in
KitAuditOptions.ResolvedSubjectActions. A user's entity type is one inKitAuditOptions.UserEntityTypes, or the class name of the identity's own user (the context'sTUser), which audit capture stamps on a data change of a user. A row with a blank action is never looked up, since its entity id may be text a caller typed. - A user the viewer's rules scope admits shows as the rules' display name. Any other id shows as a fragment
(
AuditDisplay.IdFragment), as it does with no lookup. - When the lookup fails,
NamesUnavailableis true on the page or the record, and a screen says so. The framework'sUserAdministrationwrites the Error. - With no
IUserAdministrationRules<TUser, TKey>registered, nothing is looked up and nothing is logged for it.
The viewer is read as the users seam reads the acting user. Both sets of KitAuditOptions compare exactly as stored;
an app changes them with services.Configure<KitAuditOptions>(...):
| Option | Default | Change it when |
|---|---|---|
UserEntityTypes |
User |
An app records rows of its own whose entity id is always a user's id, under another entity type. The identity's own user class needs no entry. |
ResolvedSubjectActions |
The user screens' users.* actions |
An app records an action of its own whose entity id is always a user's id. It is an allow-list: an action keyed by typed text is never added. |
A KitAuditRecord of a user's entity type is checked once with IKitUsers.GetAsync of its entity id. The check
follows the users seam's reach rule, the rules' scope and their roles, which is stricter than the scope alone that
names follow. These make the record Restricted:
- any answer but
Done: a user out of reach or missing (NotFound), a refused viewer (ActorRefused) or a fault (Failed); - an entity id that is not a user's key: the record is not
Linkableand its action is not inResolvedSubjectActions, so the id may be text a caller typed. It is restricted with no check, so the text never reaches the users seam's log; - a blank entity id, also with no check.
A restricted record keeps who did what to whom and carries no Changes, no Snapshot and no UserIp: an email
change stores the previous address, and an address is personal data. Any record also withholds its actor's UserIp
unless the lookup names the actor for the viewer: an actor out of the viewer's scope and a failed lookup both withhold
it, and NamesUnavailable says which. A record's one lookup asks for its actor's id even when a name is stored, and
the stored name still shows; the answer decides the address only. A record with no actor id keeps its UserIp, since
no lookup can name its actor, so the record page shows it with ShowIp to every viewer unless the record is
Restricted. A list shows no address and makes no such check.
With no rules registered, nothing is looked up, no record is restricted and every address shows: no scope is defined, so the audit page's permission is the only gate. Grant that permission only to roles that may see every user.
The words of an action
KitAuditLabels (Solhigson.Admin.Auditing) gives the words an audit screen shows for an action. Every text is
unencoded; the screen encodes it.
| Member | Gives |
|---|---|
For(category, action, entityType) |
The action's label in a list. A package action has its own label (table below). Any other action gets the framework's AuditDisplay.ActionLabel: a data change reads as its verb and entity type ("Update Invoice"), a blank action reads as its category's label ("Security Event"), and any other action reads as stored. |
Sentence(category, action, entityType, actor, subject) |
The record as a sentence. A package action reads <actor> <verb phrase> <subject>, such as "Ada Obi changed the roles of Jane Doe". Any other action reads <label>: <subject>, by <actor>, with the label from For. A label that names the subject's type, a data change's, is followed by an unnamed subject, its type and its id fragment, as its fragment alone, so the type is said once: "Update Invoice: inv-1, by Ada Obi". A stored subject name that starts with the type and " · " loses that prefix in the sentence too; the record's Subject field keeps it. A blank actor reads "System" (AuditDisplay.SystemActor). With a blank subject a verb phrase has no object, so every action then reads <label>, by <actor>. The names are joined as given, unmarked, so a subject's name, such as a role's, can imitate an actor clause. The sentence is therefore not the record's attribution on its own: a screen that shows it shows the Actor field beside it. |
TypeInWords(entityType) |
"user" for User, "role" for Role and "setting" for AppSetting, compared exactly as stored. Any other type reads as stored, and a missing type gives an empty string. |
An action belongs to the package only when it matches exactly as stored, letter case included. An app's own actions read as stored, so an app that wants words stores a readable action name. The package's actions and their words:
| Action | Label | Verb phrase |
|---|---|---|
settings.saved |
Setting saved | saved |
settings.reset |
Setting reset to its default | restored the default of |
settings.stray-removed |
Stray setting removed | removed the stray setting |
users.enabled |
User enabled | enabled |
users.disabled |
User disabled | disabled |
users.unlocked |
User unlocked | unlocked |
users.two-factor-reset |
Two-factor reset | reset the two-factor sign-in of |
users.roles-changed |
Roles changed | changed the roles of |
users.email-changed |
Email address changed | changed the email address of |
users.created |
User created | created |
users.password-link-sent |
Password link sent | sent a password link to |
roles.created |
Role created | created |
roles.permissions-changed |
Permissions changed | changed the permissions of |
roles.outside-grants-removed |
Grants outside the group removed | removed the grants outside the group from |
roles.deleted |
Role deleted | deleted |
KitAuditLabels holds the package's one list of the actions it records, and Linkable reads it too; this table
shows that list. A new action constant on KitAuditActions, KitUserAudit or KitRoleAudit needs a label and a verb
phrase in KitAuditLabels. Without them the package's reflection test fails, and the action's rows are not
Linkable.
Every answer carries a KitAuditOutcome and a Message from KitAuditMessages.For:
| Outcome | Message |
|---|---|
Done |
Done. |
NotAvailable |
The audit trail is not available: no audit reader resolves for the app's context, or the context does not map AuditTrail. When resolving threw, the app's log holds the cause. |
ActorRefused |
Sign in to read the audit trail: the request names no signed-in user, so nothing was read. |
NotFound |
Audit record not found. |
Failed |
The audit trail could not be read, so nothing is shown. Try again; the app's log holds the cause. |
The viewer must be signed in and carry a user id, read as the users seam reads the acting user (see
The acting user). Otherwise the answer is ActorRefused, and nothing is read or said about the
set-up. A failed result from the reader is Failed with the sentence above, never the reader's own message. Nothing
throws except the caller's cancellation.
The seam writes these lines under Solhigson.Admin.Auditing.KitAuditReader. A search's line names the filters set,
never their values, since an entity id or an actor id can be text a caller typed:
| Line | Level | Text | What to do |
|---|---|---|---|
KitAuditReaderNoActor |
Warning | The audit reader 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 identity carries the claim ClaimType names, or set IdentityOptions.ClaimsIdentity.UserIdClaimType to the claim it does carry. |
KitAuditReaderSearchFailed |
Error | The audit reader seam {Method} failed: window {From} to {To}, filters set {FiltersSet}, cursor given {CursorGiven}; nothing was shown. | The line carries the exception. Check the audit store; a window that is empty means the fault came before the window was placed. |
KitAuditReaderGetFailed |
Error | The audit reader seam {Method} failed: record [{Id}], created key [{CreatedKey}]; nothing was shown. | The line carries the exception. Check the audit store. The id and key are percent-encoded and cut to 64 characters with a ... marker. |
KitAuditReaderUnresolved |
Error | The audit reader seam {Method} failed: resolving the audit reader of {ContextType}, or the context, threw; the audit trail reads as not available for the rest of the request. | The line carries the exception. Method is the first member that resolved the reader: available, or a signed-in viewer's search or get. A throw while resolving answers NotAvailable, never Failed. Fix the registration of the reader or the context it names. |
A failed result from the framework's reader is logged by the reader under AuditTrailReader; the seam writes no
second line for it.
The lines the audit screens cause
The audit screens write no line of their own. Beside the seam's lines above, the calls a read makes into the framework
and the users seam write their own lines. The framework's reader writes these under AuditTrailReader, a search's
naming the filters set and never their values. Each carries the exception, whose message is the provider's own:
| Level | Text | When | What to do |
|---|---|---|---|
| Error | Audit trail search failed on {ContextType}: window {From} to {To}, page size {PageSize}, cursor given {CursorGiven}, {ElapsedMs} ms, filters set {FiltersSet}. | A list's search threw inside the framework's reader. The screen shows the Failed alert. |
Read the exception and check the audit store. |
| Error | Audit trail get failed on {ContextType}: created {Created}, {ElapsedMs} ms. | A record's read threw inside the framework's reader. The page shows the Failed alert. |
As for a search. |
The name lookup and a record's reach check write under UserAdministration
(UserAdministrationDiagnostics.LoggerCategory), by ids or counts only, never a name, a filter's value or an
exception's message. The lookup's lines, resolve_display_names, name the count of ids passed and no id; the reach
check's, can_administer, name the viewer's id and the record's user id:
| Level | Text | When | What to do |
|---|---|---|---|
| Warning | User administration {Operation} of {IdCount} ids refused: the actor is not a stored, enabled user | A list or a record read by a signed-in account that is disabled or no longer stored. Its people show as id fragments. | The account's session outlived its disable or delete: end its sessions. |
| Error | User administration {Operation} of {IdCount} ids failed at step {Step}: {ExceptionType} | The lookup threw. The screen says "Names could not be loaded". | Read the step and the exception's type, and check the store and the app's rules. |
| Warning | User administration {Operation} by actor {ActingUserId}: target {TargetUserId} not found within its reach | A record about a user the viewer may not reach, or one no longer stored. The record is Restricted. |
Expected for a viewer outside the user's scope or roles. A rise: records about users out of reach are being opened. |
| Warning | User administration {Operation} refused: actor {ActingUserId} is not a stored, enabled user (target {TargetUserId}) | A record about a user, read by a signed-in account that is disabled or no longer stored. The record is Restricted. |
As for the lookup's refusal: end its sessions. |
| Error | User administration {Operation} failed for actor {ActingUserId} and target {TargetUserId} at step {Step}: {ExceptionType} | The reach check threw. The record is Restricted. |
Read the step and the exception's type, and check the store and the app's rules. |
The reach check is the users seam's GetAsync: a step of it after the reach that throws writes KitUsersFailed, method
get, under Solhigson.Admin.Users.KitUsers (see Log lines), by ids and the exception's type only, and
the record is Restricted. The users seam's KitUsersNoActor is never written for it, since the reader refuses that
viewer first. Each lookup adds one to the counter user_administration (see The framework's lines and
counters), tagged method resolve_display_names, and each reach check one tagged
can_administer. With no rules registered no such call is made, and none of these lines is written.
The audit screen
KitAuditList lists the audit records of one window, newest first, one page at a time, through
IKitAuditReader.SearchAsync. A component cannot be given a route, so the app writes the page:
@page "/admin/audit"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("audit.view")]
<KitAuditList DetailHref="~/admin/audit/{id}/{created}" TimeZone="@AppZone" />
| Parameter | Required | What it does |
|---|---|---|
DetailHref |
yes | The address of a record's page: a path on this site that holds {id} and {created}. Each row's id, in its "D" form, replaces {id}, and its CreatedKey replaces {created}, each url-encoded; the link then goes through KitHref.Local. A DetailHref without both, or one KitHref.Local refuses with a value in place, throws when the screen renders. Pass the two values to IKitAuditReader.GetAsync as the record's page receives them. |
TimeZone |
no | The viewer's zone: the days searched, the window's words and each record's time are in it. UTC when not set. |
The app must call AddSolhigsonAdmin (see Reading the audit trail) and map AuditTrail
in the context it passes. The page must require a signed-in user, since the screen passes the request's
HttpContext.User. Today is the viewer's day at the instant the seam read the window at (KitAuditPage.ReadAt),
so the header, the presets and the rows never disagree about it.
The screen has these parts, in this order:
- The header, "Audit trail". Its line says the window searched, in the viewer's zone, with the zone named: "Today,
10 Nov 2026 (UTC)", or "1 Nov 2026 to 10 Nov 2026 (UTC)", the second day the last one searched. A search that names
a subject or a person and no day reads all time, and says "History of
<subject>" or "Activity by<person>", each as a fragment of its id. The header's actions are "Today", "Last 7 days" and "Last 30 days": the filters in force over those days, each ending today. The one that is the window is markedaria-current="page". - The filters: the first day and the last day, and the category. Under them, "More filters" holds the action, the subject's type, the subject's id and the person's user id. It is open when any of them holds a value.
- The table: when, what, the subject and the person. "When" is the record's date over its time of day, in the viewer's zone; the column's title names the zone. "What" is the action's label, which links to the record's page, with its category under it. The subject is hidden in a narrow table; the person stays. No row carries a colour.
- The pager: "Next page", and "First page" only when a cursor was given.
The filters are a GET form, so a filtered list has an address a user can keep:
| Filter | Field | Values | Search |
|---|---|---|---|
| From | from |
A day, yyyy-MM-dd |
FromDay |
| To | to |
A day, yyyy-MM-dd, searched whole |
ToDay |
| Category | category |
DataChange, SecurityEvent, BusinessEvent |
Category |
| Action | action |
The action as stored, such as users.enabled |
Action |
| Subject type | type |
The entity type as stored, such as User |
EntityType |
| Subject id | id |
The entity id as stored | EntityId |
| Person's user id | actor |
The acting user's id | ActorUserId |
The settings screen, the role page and the user page link to this page through their HistoryHref with these names:
a setting's history by type and id, a role's by type and id, a user's by id alone, and a person's activity
by actor, each with no day. An app whose audit page reads other names gets links that filter nothing, so its page
must be KitAuditList, or read these names.
Each filter matches exactly, letter case included: the reader offers no search inside a value. A day in any other
form, a category that is not one of its names (7, datachange) and a blank value are ignored, and the field shows
empty. A cursor that does not parse serves the first page.
The pager and the presets keep the filters as they were given, the presets each with its own days, never the window
the filters resolved to, so a person's whole history stays whole on the next page. A search with no day that names
no subject or person carries the day it read, so its pages never cross a midnight. Every link goes through
KitHref.Local, each name and value escaped with Uri.EscapeDataString.
A subject links to its history only when the row is Linkable. A person links to their activity only when the
row's ActorLinkable says the actor id is a user's key: on a Linkable row, or on a row whose actor the viewer's
name lookup named. A sign-in event's entity id and actor id may be text the caller typed, so the screen puts neither
in a link, which an access log would record. An actor with no id whose name the row stores, on a sign-in or other
security event that is not Linkable (ActorAttempted), is the identity a caller gave, such as a failed sign-in's
user name. It reads "Attempted as <name>", muted, since a caller may give the name "System" or another person's.
The framework's own unattributed name is no attempt and is not marked. No id longer than its fragment shows as
text; a full id is only in a link or in a field the viewer filled in.
The filter bar is a plain GET form, never an enhanced one: its field action hides the form's own action from a
script, so Blazor's enhanced submit would fetch a wrong address. Applying the filters loads the page whole.
Empty states and alerts of the audit screen
With no rows and a category or an action set, the screen shows "No records match these filters", with a link that clears every filter. Otherwise it shows "No activity in this window", with the window searched, and one remedy:
- On a search of a subject or a person with days, "All dates": the same filters with no day, so all time.
- On a search of no subject or person, "Last 30 days", unless the window already holds all of those days.
- On a search of a subject or a person with no day, which read all time, none.
| Outcome | What the screen shows |
|---|---|
Done with NamesUnavailable |
A Warn alert, "Names could not be loaded", above the rows. |
NotAvailable |
A Warn alert of the outcome's Message alone, which names the reader and the AuditTrail mapping the app's context needs. |
ActorRefused, Failed |
A Danger alert of the outcome's Message alone, and no table. |
The screen writes no log line; the seam's lines, and those its reads cause (see The lines the audit screens cause), are above.
The audit record page
KitAuditDetail shows one audit record, whole, through IKitAuditReader.GetAsync. The app writes the page, with
the record's id and created key in its route, the address the list's DetailHref names:
@page "/admin/audit/{Id}/{Created}"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("audit.view")]
<KitAuditDetail Id="@Id" Created="@Created" ListHref="~/admin/audit" UserHref="~/admin/users/{id}" TimeZone="@AppZone" />
@code {
[Parameter]
public string? Id { get; set; }
[Parameter]
public string? Created { get; set; }
}
| Parameter | Required | What it does |
|---|---|---|
Id |
yes | The record's id, as the route gives it. |
Created |
yes | The record's created key, as the route gives it. |
ListHref |
yes | The audit screen's page: a path on this site with no query or fragment of its own. The header's "Audit trail" link and the not-found page's way back go to it, and every link to the list adds the list's query to it. A ListHref that KitHref.Local refuses, or one holding ? or #, throws when the page renders. |
TimeZone |
no | The zone the record's time shows in; UTC when not set. The time names the zone's id. |
UserHref |
no | The address of a user's page: a path on this site that holds {id}, which the actor's id replaces, url-encoded. The person's "User page" link goes to it, only when the actor's id is a user's key (ActorLinkable). A UserHref without {id}, or one KitHref.Local refuses with a value in place, throws when the page renders. |
ShowIp |
no | Whether the page shows the address the record came from. 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 record not found is answered with 200, not 404. That
page shows the header "Audit record" and the empty state "Record not found", with "Audit trail" 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 Reading the audit trail) and map AuditTrail
in the context it passes. The page must require a signed-in user, since the page passes the request's
HttpContext.User.
An app that captures its user class, so that a user's data change is recorded, adds "securitystamp" to
AuditCaptureOptions.AdditionalSensitiveNamePatterns, through a pre-populated AuditCaptureOptions singleton of its
own, which the framework's registration (PreserveExistingDefaults) leaves in place. The framework's default patterns
(AuditFieldMasker.DefaultSensitiveNamePatterns) do not mask SecurityStamp, so the row would store it as it is, and
this page would show it. A pattern masks any property whose name holds it, letter case ignored, so "securitystamp"
masks the secret and nothing else, where a plain "stamp" would also mask any Timestamp column.
Rows captured before the pattern keep the raw stamp. An app that has already captured its user class adds the pattern,
then rotates every user's security stamp (UserManager.UpdateSecurityStampAsync) before it grants the audit page's
permission; rotating ends every open session at the next stamp check. An app never opts Identity's user-token,
user-login or user-claim types into capture, since their values are credentials no pattern masks and their records are
not Restricted.
The page has these parts, in this order:
- The header. Its title is the record as a sentence (
KitAuditRecord.Sentence), so the action is said once. Its line says when the record was written, in the viewer's zone, to the second, as the list's time column does, with the zone named as the list names it: "10 Nov 2026, 11:58:00 (UTC)". Then a quiet "Audit trail" link back to the list. - A Warn alert, "Names could not be loaded", when the record's
NamesUnavailable, as on the list; a Neutral alert, "Details withheld", when the record isRestricted. - The facts: the category; the action as stored, the one place it shows, with "All records of this action"; the
subject, with "History of this
<type>" only when the record isLinkable; the person, read "Attempted as<name>" for an identity a caller gave, with "Activity by this person" and, withUserHref, "User page", each only whenActorLinkable; the source; and the address, only withShowIp. - "What changed", a table of each field before and after, when the record holds changes; "Recorded values", a table of each field and its value, when it holds a snapshot. A record with neither says "No field values were recorded."
"All records of this action" lists every record of the stored action from the first day of all time to today, since
an action names no subject or person, and the list would otherwise read today alone. The history and the activity
links read all time, as the list's own do. Each link is built through KitHref.Local on ListHref, with the list's
query names, each value escaped with Uri.EscapeDataString, so an entity id holding &, # or // reads back as
itself. No full id shows as text: the subject and the person show as their fragments, and the record's source id is
not shown.
A value equal to the capture's mask (AuditFieldMasker.MaskMarker, ***) or the settings' mask
(SettingsCatalog.Mask) reads "Hidden"; a null reads "Not set", an empty string "Empty", and a value of white space
alone "White space only". Each is muted, so a blank cell never stands for any of them. Any other value keeps its
white space, and a value that starts or ends with white space is tinted to its extent, so a trailing space reads as
a change. The reader unmasks nothing. A payload that is not the stored shape
shows as stored under "Shown as stored", as text, in a block that scrolls inside itself, reached by keyboard as a
region named for its section. Its height is the component token --kit-audit-raw-height, the measure unless the
app sets it. Nothing in a record is ever markup: every value is written as text, encoded.
The address a record came from is personal data: the page shows it only with ShowIp, and never for a Restricted
record. The seam gives no address either when the viewer's name lookup did not name the actor; the fact then reads "Not
available". A record with no actor id keeps its address, which ShowIp shows to every viewer unless the record is
Restricted, so an app turns ShowIp on only where the address may be shown to every holder of the audit page's
permission.
| Outcome | What the page shows | Status |
|---|---|---|
Done |
The record. A Done answer with no record, which only an app's own seam can give, shows the Failed alert. |
200 |
NotFound |
The header "Audit record" and the empty state "Record not found", with "Audit trail" as its action. | 404, when the response has not started |
NotAvailable |
A Warn alert of the outcome's Message alone, under the header "Audit record" and its "Audit trail" link. |
200 |
ActorRefused, Failed |
A Danger alert of the outcome's Message alone, under the header "Audit record" and its "Audit trail" link. |
200 |
A record restricted for the viewer keeps who did what to whom, says its values and address are not shown, since the record is about a user the viewer may not see or one the page cannot check, and shows no value, no section and no address. The page writes no log line; the seam's lines, and those its reads cause (see The lines the audit screens cause), are above.
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 overSolhigsonAspNetRoleandstring.AddSolhigsonAdmin<TUser, TKey, TContext>()closes it overSolhigsonAspNetRole<TKey>andTKey.
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, asUserManager.GetUserIdAsyncgives it.DisplayName: the rules'DisplayName, else the email.Email,EmailConfirmedandUserName.Roles, ordered.Enabled,TwoFactorEnabledandHasPassword.LockedOutUntil: set only when lockout is on for the account and its end is after now. The clock is the registeredTimeProvider, 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, the audit record page's reach check, and the reach of a role change and of a two-factor reset), resolve_display_names (the audit screens' name lookup), 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. |
Roles
IKitRoles (Solhigson.Admin.Roles) is the one seam through which the role screens read roles. A screen injects
this one type, whatever the app's user and key types. AddSolhigsonAdmin registers it, scoped, over the framework's
RoleAdministration that AddSolhigsonIdentityManager registers with the same type arguments, closed as IKitUsers
is (see Users). A seam the app registered first is kept. The framework decides what the signed-in user may
do with each role; the seam adds no rule and hides no outcome. The app must register its
IUserAdministrationRules<TUser, TKey>, else every call but GroupNamesAsync answers NoRules for a signed-in
actor.
| Member | Answers | What it reads |
|---|---|---|
ListAsync(principal, ct) |
KitRolePage (Rows, Outcome, Message) |
The framework's ListAsync: every stored role, ordered by group name then name. A role's name and size are not secret to an administrator, so every role is listed, whether or not the signed-in user may edit it. |
GetAsync(principal, roleName, ct) |
KitRoleLookup (Row, Outcome, Message) |
The framework's GetAsync. It takes the role's name as a Razor component page's route value gives it; never decode that value again. A name that differs from the stored one only by letter case finds the role. A name null or blank, or one no role has, answers RoleNotFound. |
HeldPermissionsAsync(principal, roleName, ct) |
KitHeldPermissions (Permissions, Outcome, Message) |
The framework's HeldPermissionsAsync: every stored grant of the role, as a HeldPermission with its class against the role's group's offer (Offered, OutsideGroup, NoDeclaration, UnknownGroup, Missing) and whether RemoveGrantsOutsideOfferAsync would remove it (Removable), whether or not the signed-in user may edit the role. The framework finds the role by its name exactly as stored, so pass the Name that GetAsync answered, not the route value. A name null or blank, or one no role has, answers RoleNotFound. |
OfferedPermissionsAsync(principal, roleName, ct) |
KitOfferedPermissions (Permissions, Outcome, Message) |
The framework's OfferedPermissionsAsync: every permission the role's group may hold, as an OfferedPermission with whether the role holds it (Held), whether the signed-in user may give it (Grantable) and its top-most offered ancestor (TopId), in the editor's order. Only for a role the signed-in user may edit: one they hold answers NotOwn, one outside their grant RoleOutOfReach. Pass the Name that GetAsync answered. |
SetPermissionsAsync(principal, roleName, ids, loadedHeldIds, ct) |
KitRoleResult |
The framework's SetPermissionsAsync: the role holds exactly ids among its offer, and an offered permission it holds that ids leaves out is revoked. The framework writes nothing and answers Stale when the offered permissions the role holds now are not loadedHeldIds, and PermissionOutOfReach when the set adds one the signed-in user may not give; removing one needs no grant. Done carries Granted and Revoked (names as stored), Dropped (the ids posted that were not given) and CacheConfirmed; Unchanged, nothing added or removed, carries Dropped. Neither carries a Row: read the role again. |
RemoveGrantsOutsideOfferAsync(principal, roleName, ct) |
KitRoleResult |
The framework's RemoveGrantsOutsideOfferAsync: removes the role's grants outside its group's offer that the framework judges removable, those HeldPermissionsAsync marks Removable, judged again as it runs. An undeclared menu root and a name the database matches to a declaration allowing the group are outside the offer but kept. Done carries Revoked (names as stored), RemovedMissingIds (the removed grants naming no stored permission), which together count every grant removed, and CacheConfirmed; Unchanged removed nothing, as with no permission groups registered. A role whose group is not a known group answers GroupNotFound, nothing removed. Neither carries a Row: read the role again. |
CreateAsync(principal, roleName, roleGroupName, ct) |
KitRoleResult |
The framework's CreateAsync: a role named roleName, trimmed, in the stored group roleGroupName names, holding no grant. The framework refuses, writing nothing, with InvalidName (blank, over RoleAdministration.MaxRoleNameLength, 64 characters; holding a slash, a backslash, an invisible character, two spaces in a row or a space other than U+0020; or not in Unicode's composed form, NFC: RoleAdministration.CreateAsync lists every case), GroupNotFound, RoleExists (a role of the name in any letter case), GroupOutOfReach, when the app's rules' MayCreateRoleAsync answers false, which it does unless the app writes it, or InTransaction, when the scope's context has a transaction open or an ambient one is, since the create commits its own. Done carries the new role as its Row, read back by the framework; its CanEdit false means the role is outside the signed-in user's own Grant answer, so someone whose answer holds it must set its permissions. Once Identity's save has returned, or where a cancellation that interrupts it throws as one (SQLite, PostgreSQL) and the role is stored, the framework answers Done; on SQL Server such a cancellation is rethrown though the role may be stored. |
DeleteAsync(principal, roleName, ct) |
KitRoleResult |
The framework's DeleteAsync: removes the role and every grant it holds. The framework finds the role by its name exactly as stored, so pass the Name that GetAsync answered. It refuses, removing nothing, with RoleInUse when any user holds the role, in any tenant, NotOwn for a role the signed-in user holds, RoleOutOfReach for one outside their grant, RoleNotFound, InTransaction, since the delete commits its own, or IdentityFailed, when Identity refuses the write. Done carries the role as it was as its Row, RemovedPermissionNames (the names its grants named, as stored), RemovedMissingIds (its grants naming no stored permission) and CacheConfirmed. Failed may follow a commit, so read the role again to learn whether it is still stored. Once the role is deleted the framework answers Done even when the request is cancelled. Once a role of the name exists again, whether the app's seed or an administrator creates it, the framework's permission seed gives it, each time the seed runs (an app runs it at start-up), every grant whose permission names it in AllowedRoles and that its group may hold; remove the name from those declarations too. No session is ended: a role created again under the name gives its grants to any open session whose role claims still carry the name, until that session's stamp is next checked; an app that does not end sessions on a role change lets that interval pass before reusing a name. |
PermissionsAsync(principal, ct) |
KitPermissionPage (Rows, GroupsRegistered, Outcome, Message) |
The framework's PermissionsAsync: every stored permission, enabled or not, as a CataloguedPermission, in the editor's order. Each carries its parent's name and description, the groups its declaration allows (Groups, null for a permission with no declaration, which is offered to no group) and the roles holding a grant of it (Roles, each a CataloguedRole with its id as text and its name). The roles come from one query joining the grants to their roles, read as ListAsync reads the roles, so an app's query filter on the roles applies to both; a grant naming no stored role names none. GroupsRegistered is false when the app registers no permission groups, and then no permission has groups. A permission's name and holders are not secret to an administrator, so every permission is listed, whatever the signed-in user may grant. |
GroupNamesAsync(ct) |
KitRoleNames (Names, Outcome, Message) |
Every stored role group's name, ordered ordinally, read from the database for the call. The framework has no read of every group, so the seam reads the context's RoleGroups. It names no acting user. |
The acting user is read as the users seam reads it (see The acting user). A principal that names
no acting user answers ActorRefused and reads nothing. A screen passes the request's HttpContext.User.
A KitRoleRow holds:
Id: the role's key as text, a Guid key in its "D" form.Name: the role's name as stored; null for a role stored with none.GroupNameandGroupKnown.GroupKnownis false only when the app registers permission groups (AddPermissionGroups) and the role's group is not one of them.HolderCount: the users holding the role in every tenant, never the viewer's scope.GrantCount: every stored grant of the role, those outside its group's offer included.HeldByViewer: whether the signed-in user holds the role.CanEdit: whether the signed-in user may edit the role's permissions. It is as stored when read; a write decides again.
Every answer carries the framework's UserAdministrationOutcome and a Message from KitUserMessages.For. The role
outcomes each have their own sentence: InvalidName, GroupNotFound, RoleExists, GroupOutOfReach,
PermissionOutOfReach, Stale and RoleInUse. The one exception is RemoveGrantsOutsideOfferAsync's
GroupNotFound, which says "Nothing was removed: this role's group is not a declared permission group.", since the
shared sentence speaks of a group chosen on the create screen. An outcome no version of the package knows gets one
fixed sentence: "The answer is not one this version of the admin package knows; nothing more was done." Nothing throws
except the caller's cancellation.
Each write the role screens make is added to the seam by the change that uses it. Every write answers KitRoleResult
(Outcome, Message, Row, Granted, Revoked, Dropped, CacheConfirmed, RemovedPermissionNames,
RemovedMissingIds). A save from a page whose role changed since it was rendered is the framework's own outcome
Stale, never a flag; the removal of the grants outside the offer judges each grant again as it runs, so it has no
Stale, and a page that counted grants since removed gets Unchanged. RemovedMissingIds holds the ids of removed
grants whose permission is no longer stored, so the names and these ids together count every grant removed.
Links to a role
KitRoleLinks.For(template, name, context) builds every link to a role. The template is the app's address, holding
{name} (~/admin/roles/{name}) or {role} (~/admin/users?role={role}). Each token is replaced by the name,
url-encoded with Uri.EscapeDataString. The link then goes through KitHref.Local, with the request's path base.
On a Razor component page, the route value of the link's segment is the name as stored: a name with a space, ?,
#, %, a literal %41 or a slash arrives whole. Pass the route value to GetAsync as it is, and never decode it
again: a second decode would open a%41 as the role aA, and fail on 50% off. The link is null when:
- KitHref refuses it, such as for a name of
..; - the template is empty or holds neither token;
- the name is null or empty;
- the name holds a literal
%2Fand a token is in the address's path, before its first?or#. ASP.NET Core decodes the request's path but its%2F, and the Blazor router decodes that%2Fafter, soa%2Fbwould arrive asa/b, another role's name. In the query or the fragment the name arrives exact.
Auditing role changes
KitRoleAudit holds the audit vocabulary for the role screens. The entity type is Role, the entity id is the
role's id, and the subject's display name is the role's name on every event, so a row names a deleted role. The
actions are roles.created, roles.permissions-changed, roles.outside-grants-removed and roles.deleted. Each is
recorded as a SecurityEvent through IKitAudit (see Recording changes). A change whose row
was not written says so in the change's one alert, in Warn, and the audit seam writes its own Error, as on the user
page.
The roles seam's log lines
The seam writes these lines under Solhigson.Admin.Roles.KitRoles, in the users seam's shape. A line carries ids
only, never a role's name or an exception's message. Before the seam reads a role, the target is roles for a list,
role for one role, groups for the group names, new for a create and permissions for the permissions catalogue;
then it is the role's id. An id is
percent-encoded and cut to 64 characters with a ... marker.
| Line | Level | Text | What to do |
|---|---|---|---|
KitRolesNoActor |
Warning | The roles 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. |
KitRolesFailed |
Error | The roles seam {Method} failed at step {Step}: {ExceptionType}; actor [{ActingUserId}], target [{TargetRoleId}]. | Read the step. Read means the role group table could not be read; ActingId means the principal could not be read; Row means a role the framework answered could not be shown; Call means the framework answered done with nothing in it. Check the store, or report the line. |
A fault inside the framework's own call is answered Failed by the framework, which writes its own Error under
RoleAdministration (see The framework's role lines and counter). The seam
writes no second line for it.
The role pages write their audit rows through the user screens' guard, so two of its lines, under
Solhigson.Admin.Users.KitUserSeams (see The app's sessions and notices), are the
role pages' too: KitUserSeamAuditFailed, an Error, when the app's audit seam throws as a role change is recorded,
naming the entity type Role and the role's id, the row not written; and KitUserSeamDoneUnnamed, an Error, when an
app's own IKitRoles answers a create done with no role in it, so roles.created is not recorded. A row the audit
seam itself fails to write is its own Error, KitAuditFailed or KitAuditUnsaved, and an app whose changes are not
recorded gets KitAuditOff once a process (see Recording changes). The four screens write no
other line of their own.
The framework's role lines and counter
Each call the seam makes into the framework writes the framework's own lines under RoleAdministration
(RoleAdministrationDiagnostics.LoggerCategory), by ids only, never a role's name, a user's name or an email; a
create's Information line also names the stored group. Each line names the operation (the counter's method, below),
the acting user's id and the role's id, or, before the role is read, roles for a list, role for one role, new
for a role not yet created and permissions for the permissions catalogue. An Error is a fault; a Warning an attempt
outside reach, or a write refused.
| Level | Text | When | What to do |
|---|---|---|---|
| Error | Role administration {Operation} refused for actor {ActingUserId} and role {RoleId}: no {Registration} is registered for the user type {UserType} | Any call, while the app registers no rules. | Register the app's IUserAdministrationRules<TUser, TKey>, the one the user screens need. |
| Warning | Role administration {Operation} refused: actor {ActingUserId} is not a stored, enabled user (role {RoleId}) | Any call by a signed-in account that is disabled or no longer stored. | The account's session outlived its disable or delete: end its sessions. |
| Error | Role administration {Operation} failed for actor {ActingUserId} and role {RoleId} at step {Step}: {ExceptionType} | A step threw: the database, the app's rules (such as step MayCreateRoleAsync), or a delete on an engine other than PostgreSQL, SQL Server or SQLite (step Provider, NotSupportedException). It also follows a save, a removal or a delete whose commit threw, other than by the caller's cancellation, and whose read back found it stored; that write answers as it would have. |
Read the step and the exception's type; the exception's message is never logged. A write answered Failed may have been stored, and a create's line names the role's id only once the role is known stored, else new: look the role up before doing it again. |
| Error | Role administration {Operation} by actor {ActingUserId} on role {RoleId} refused: the scope's {Context} holds unsaved changes, which the call's save would commit | A create, a save, a removal or a delete, while the request's context holds changes of the app's own. | Nothing was written. The app's own code left changes unsaved in the request before the screen's call: save or discard them first. |
| Warning | Role administration {Operation} by actor {ActingUserId} refused for role {RoleId}: the app's rules do not let it create a role in the group asked for | A create the app's MayCreateRoleAsync refuses. |
Expected when the rules refuse. When every create is refused, the app has not written MayCreateRoleAsync, which refuses unless written: write it, or leave CanCreate false. |
| Warning | Role administration {Operation} by actor {ActingUserId} on role {RoleId} refused by Identity at step {Step}: {ErrorCodes} | A create or a delete Identity refused. | Read the codes. ConcurrencyFailure is a write that crossed another: reload and try again. On SQL Server, DuplicateRoleName after a cancelled request may be that request's own create: look the role up. |
| Warning | Role administration {Operation} by actor {ActingUserId} refused: role {RoleId} is outside its grant answer | An offer, a save, a removal or a delete of a role outside the viewer's Grant answer. |
The role page shows no form for such a role, so the post was made by hand, or the viewer's roles changed since the page loaded. Nothing was written. |
| Warning | Role administration {Operation} by actor {ActingUserId} refused: the actor holds role {RoleId} | An offer, a save, a removal or a delete of a role the viewer holds. | As for a role outside the grant answer. |
| Warning | Role administration {Operation} by actor {ActingUserId} refused for role {RoleId}: {Count} permission ids to add are outside what the actor may give | A save adding a permission the viewer may not give. | A disabled box posted by hand, or the viewer lost a permission since the page loaded. Nothing was saved. |
| Warning | Role administration {Operation} by actor {ActingUserId} rolled back: role {RoleId} is outside its grant answer once its permissions are written | A save that would move the role out of the viewer's reach. | Nothing was saved. Expected where the app's rules rank roles by their grants: such a role's permissions are set by an administrator whose Grant answer holds it. |
| Information | Role administration {Operation} by actor {ActingUserId}: role {RoleId} created in group {GroupName} | A create done. | Nothing. |
| Information | Role administration {Operation} by actor {ActingUserId}: role {RoleId} granted {GrantedCount} and revoked {RevokedCount} permissions; cache confirmed {CacheConfirmed} | A save done. | CacheConfirmed false: the app's other instances may honour the old permissions until their cache recovers. No value: the app runs no EF Core cache. |
| Information | Role administration {Operation} by actor {ActingUserId}: role {RoleId} revoked {RevokedCount} permissions outside its group's offer; cache confirmed {CacheConfirmed} | A removal done; the count holds the grants naming no stored permission too. | As for a save. |
| Information | Role administration {Operation} by actor {ActingUserId}: role {RoleId} deleted with {GrantCount} grants; cache confirmed {CacheConfirmed} | A delete done. | As for a save. |
A list, a lookup, a grants read, an offer answered, the permissions catalogue, a role not found, a name not valid, a
group not found, a name taken, InTransaction, a stale page, a save or removal that changed nothing, a role in use and
the caller's cancellation write no line. The XML documentation of RoleAdministrationDiagnostics lists every line.
A save also writes the permission manager's own Warnings, under Solhigson.Framework.PermissionGroups, when it posts
an id the role's group is not offered, such as from a page opened before a declaration changed: "Permission group:
{Posted} ({Permission}) was not granted to role {Role} of group {Group}: {Reason}", one for each of the first twenty
such ids, then "Permission group: and {Count} more posted ids were not granted to role {Role} of group {Group}". These
name the role and the permission by name, and are written only by a manager given a logger factory. The page's alert
counts the same ids, "1 permission sent was not given". Nothing was granted for those ids and the rest of the save
stands; a line now and then is a page opened before a declaration changed, or a post made by hand.
The page's own check of the manage or create permission, made through IAuthorizationService as the new-role page
below makes it, writes the framework's Warning "Permission refused: {Permissions} on {Route} for user {UserId}" under
Solhigson.Framework.Web.Authorization.PermissionHandler each time it refuses a signed-in viewer, as a refused
[Permission] does. For a viewer without the permission that line is expected: CanManage or CanCreate is then
false.
Each call the framework answers adds one to the counter role_administration on the meter
Solhigson.Framework.Identity, which the app adds to its metrics pipeline (AddMeter("Solhigson.Framework.Identity")),
tagged method (list, get, held_permissions, offered_permissions, set_permissions) and outcome, such as
done, actor_refused, no_rules, failed or cancelled; a removal is tagged remove_grants_outside_offer, a
create create, a delete delete and a permissions catalogue permissions. A call the seam refuses because the
principal names no acting user never reaches the framework, so the counter does not count it: KitRolesNoActor is
the count of those. A rise in failed or no_rules: read the framework's line under RoleAdministration. A rise in
actor_refused, role_out_of_reach, not_own or permission_out_of_reach: accounts that may not change a role, or
not that way, are trying.
The roles screen
KitRolesList lists every stored role through IKitRoles.ListAsync, ordered by group, then name. A component cannot
be given a route, so the app writes the page:
@page "/admin/roles"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("roles.view")]
<KitRolesList DetailHref="~/admin/roles/{name}" CreateHref="~/admin/new-role" UsersHref="~/admin/users?role={role}" />
| Parameter | Required | What it does |
|---|---|---|
DetailHref |
yes | The address of a role's page: a path on this site that holds {name}. KitRoleLinks.For builds each row's link. A DetailHref without {name}, or one KitHref.Local refuses with a name in place, throws when the screen renders. |
CreateHref |
no | The address of the page that creates a role (see The new-role screen). Without it the screen offers no "New role". |
UsersHref |
no | The users list filtered by a role: a path on this site that holds {role}, such as ~/admin/users?role={role}. KitRoleLinks.For builds each link. A UsersHref without {role}, or one KitHref.Local refuses, throws when the screen renders. Without it no row links to its users. |
The app must call AddSolhigsonAdmin (see Roles) and register its IUserAdministrationRules. The page
must require a signed-in user, since the screen passes the request's HttpContext.User. The screen writes no log
line; the seam's lines are in The roles seam's log lines.
The screen has these parts, in this order:
- The header, "Roles", with "New role" as its primary link when
CreateHrefis set and a role exists. - The filter by group, a GET form, so a filtered list has an address a user can keep. Its field is
group, and its values areGroupNamesAsync's names. It shows only when a role exists and the names can be read. - The table, with four columns:
- Role: the name links to the role's page. Under it, in plain muted text, "Yours" marks a role the signed-in user holds, else "View only" marks one they may not change. A role they may change carries nothing.
- Group: not shown while the filter is set, since every row would show the same group.
- Users: the number of users holding the role, in every tenant, as plain text. With
UsersHrefand at least one holder, a separate "See the ones you manage" link sits under it. The users list shows only the users within the viewer's reach, so the number is never the link. - Permissions: the role's stored grants.
The two counts sit at the column's end in tabular figures. Users and Permissions are hidden in a narrow table. No role carries a pill: nothing on this screen needs attention. An app has tens of roles, so there is no search and no paging.
A group in the address that is not one of the names, in letter case too, is ignored. When the names cannot be read, the filter does not show and a group in the address is ignored.
A role's page receives the name as its route value; pass it to IKitRoles.GetAsync as it is (see
Links to a role). A name holding a literal %2F under a path's {name} shows as text with no
link. Its users link, in the query, carries it exact.
Empty states and refusals of the roles screen
With no role, the screen shows "No roles yet", with "New role" as its action when CreateHref is set. With the filter
set and no role in the group, it shows "No roles match", with a "Clear filter" link to the list.
When the seam answers NoRules, ActorRefused or Failed, the screen shows a Danger alert, "Roles could not be
listed", with the seam's Message. It then shows no filter, no table and no empty state.
The permissions screen
KitPermissionsList lists every stored permission through IKitRoles.PermissionsAsync, in the role editor's order,
with the groups that may hold it and the roles that do. It is read-only: a permission is declared by the app's code,
so the screen has no action. The app writes the page:
@page "/admin/permissions"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("roles.view")]
<KitPermissionsList RoleHref="~/admin/roles/{name}" />
| Parameter | Required | What it does |
|---|---|---|
RoleHref |
no | The address of a role's page: a path on this site that holds {name}. KitRoleLinks.For builds each role's link. A RoleHref without {name}, or one KitHref.Local refuses with a name in place, throws when the screen renders. Without it every role is its name as text. |
The app must call AddSolhigsonAdmin (see Roles) and register its IUserAdministrationRules. The page
must require a signed-in user. The screen writes no log line; the seam's lines are in
The roles seam's log lines.
The screen has these parts, in this order:
- The header, "Permissions". Its line gives the count, "12 permissions". With permission groups registered and a
permission offered to no group, the line also holds "3 are offered to no group", a quiet link to that filter,
marked the current page (
aria-current="page", in the text colour with no underline) while the filter is on. - The filter, a GET form, so a filtered list has an address a user can keep; a permission's name is not personal
data. Its fields are
search, text matched against the name and the description in any letter case, and, with permission groups registered,no-group, "Offered to no group". Both set, a row matches both. A blank search filters nothing. It shows only when a permission exists. - The table, with four columns:
- Permission: the description, with the name under it in the mono face; the name alone, in the mono face, when there is no description.
- Parent: the parent's description, else its name in the mono face. It is empty for no parent, or a parent that is not stored.
- Groups: the groups the permission's declaration allows, or a Warn pill "Offered to no group" for a permission with no declaration, or one naming no group: no role group may hold it.
- Roles: the roles holding it, each linking to its page with
RoleHref; "None", muted, when no role does.
Parent and Roles are hidden in a narrow table. With permission groups not registered, the Groups column and its
filter do not show, and a no-group in the address is ignored. An app with hundreds of permissions gets one long page:
the screen does not page, and the filter is the way in. A role name holding a literal %2F shows as text with no link
(see Links to a role), as does a role stored with no name, shown by its id.
Empty states and refusals of the permissions screen
With no permission, the screen shows "No permissions yet": permissions appear when the app starts and finds its protected pages. With a filter set and no match, it shows "No permissions match", its line saying which filter found nothing: "No permission holds these words in its name or description." for the search, "Every permission is offered to a group." for "Offered to no group", and "No permission offered to no group holds these words in its name or description." for both. Its link back to the list, as the filter's own, says "Clear search" when the search is the only filter set, else "Clear filters".
When the seam answers NoRules, ActorRefused or Failed, the screen shows a Danger alert, "Permissions could not
be listed", with the seam's Message. It then shows no count, no filter, no table and no empty state.
The role page
KitRoleDetail shows one role through IKitRoles.GetAsync. It says first whether the viewer can change the role,
and if not, why. The app writes the page, with the role's name in its route:
@page "/admin/roles/{Name}"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("roles.view")]
<KitRoleDetail RoleName="@Name" ListHref="~/admin/roles" UsersHref="~/admin/users?role={role}"
HistoryHref="~/admin/audit" />
@code {
[Parameter]
public string? Name { get; set; }
}
| Parameter | Required | What it does |
|---|---|---|
RoleName |
yes | The name of the role to show, as the route gives it. Never decode it again (see Links to a role). |
ListHref |
yes | The address of the roles list, a path on this site. The header's "All roles" link and the not-found page's way back go to it. A ListHref that KitHref.Local refuses throws when the page renders. |
UsersHref |
no | The users list filtered by a role, a path on this site holding {role}. Without it the Users section links nowhere. An address with no {role}, or one KitHref.Local refuses, throws when the page renders. |
HistoryHref |
no | The audit page's path on this site, alone, with no query or fragment (see The audit screen). With it, the header's line ends with a quiet "History" link to ?type=Role&id=<the role's id>, each value escaped, with no day, so the list reads the role's whole history. "History" reads the role's records by the type Role and its id: the role screens' records, not the rows audit capture may write for the app's role class under that class's name. The page after a delete keeps it, since the role's records are the one place its permissions are still named. A refusal's header has none. Without it no link renders; a value KitHref.Local refuses, or one holding a query or a fragment, throws when the page renders. |
CanManage |
no | Whether the viewer holds the permission to change roles. False unless set. With it, a role the viewer may edit gets the permissions form (see Changing a role's permissions), the removal of its grants outside its group's offer (see Removing grants outside the group's offer), and its delete (see Deleting a role). Set it from the app's own check of the manage permission; the framework still decides each change. |
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 role not found is answered with 200, not 404. That
page shows the header "Roles" and the empty state "Role not found", with "All roles" as its action. As on the user
page, ASP.NET Core 10 sends a page that sets 404 with no body; add the app's status code pages.
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.
The page refuses framing, so no other site can lay the form that changes a role's permissions 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, on the page's own read; after a save, see Changing a role's permissions, and after a delete, Deleting a role:
| Outcome | Status | The page |
|---|---|---|
Done |
200 | The role, as below. |
RoleNotFound |
404 | No body (see above), on the page's own read; after a save or a delete not done, 200 and its alert above "Role not found". |
NoRules, ActorRefused, Failed |
200 | The header "Roles", "All roles" in its line, and a Danger alert, "The role could not be shown", with the seam's Message. Nothing of the role is shown. After a save or a delete, its alert comes first. |
A role found has these parts, in this order:
The header: the role's name as its title; in its line, "Group:" and the role's group, then "All roles", a quiet link back to the list.
One sentence, the first that applies:
- "You hold this role, so another administrator changes it"
- "This role is outside what you may grant", when the role is outside the viewer's grant answer
- "You can view this role; changing it needs the manage permission", when
CanManageis false - "You can change this role"
A Warn alert, "Changes here leave no audit record", when
CanManageis set and the app'sIKitAuditdoes not record (see Recording changes).Permissions (id
permissions). A Warn alert first when the role's group is not a declared permission group: the role can be given nothing until the app declares the group in code. Then what the role holds (IKitRoles.HeldPermissionsAsync), shown to every viewer: read-only, unless the permissions form takes the place of the grants its group offers (see Changing a role's permissions). The grants its group offers come in one block for each top permission, in the editor's order. A block's top, when the role holds it, heads the block; else, when every grant in the block hangs from that top, the top's name heads it, muted. Each grant is labelled by its description, or by its name in the mono face where the description is empty. Under "Not offered to this role's group" follow the grants outside the offer, each with its class in words:- "Declared for other groups, not this role's" (
OutsideGroup) - "Offered to no group: no declaration names it" (
NoDeclaration) - "This role's group is not declared, so it is offered nothing" (
UnknownGroup) - "Its permission no longer exists, so it gives no access" (
Missing), labelled by the id the grant names - "Not offered, for a reason this version of the admin package does not know", for a class a later framework adds
Where the viewer may change the role, "Remove these 3" follows the list (see Removing grants outside the group's offer), and each grant listed that the removal keeps has a second muted line, "Kept when the others are removed", so the grants without it are the 3.
A role holding nothing says "This role holds no permission"; one holding only grants outside the offer says "This role holds nothing its group offers". When the role's group is not declared, its alert says why, so the second line does not show and no
UnknownGroupgrant repeats it; a role holding nothing still says so. When the grants cannot be read, the section shows a Danger alert, "The role's permissions could not be read", with the seam'sMessage.- "Declared for other groups, not this role's" (
Users (id
users): "No user holds this role", or "Held by 12 users in all", every tenant counted. WhenUsersHrefis set and a user holds the role, a quiet link, "See the ones you manage", opens the users list filtered by the role, which shows only the users within the viewer's reach. The section ends in a region for its action: "Delete role" where the viewer may delete the role and no user holds it (see Deleting a role), else empty.
The page writes no log line of its own.
Changing a role's permissions
With CanManage set, a role the viewer may edit (CanEdit, and not held by the viewer), and a page address that
KitHref.Local accepts, the Permissions section reads IKitRoles.OfferedPermissionsAsync and shows one form,
role-permissions, in place of the read-only list of offered grants. The grants outside the offer still follow it.
The form posts to the page's own address with #permissions, and holds:
- the ids of the offered permissions the role holds, as rendered, one hidden
loadedfield each; - "Greyed-out permissions are ones you do not hold; you can give only what you hold.", when any box is disabled;
- one fieldset for each top permission, in the editor's order. Its legend holds the top's own box; under it is a box
for each permission below it, grandchildren included. A permission whose parent is not offered is a top of its
own, in a fieldset of its own. Each box posts its permission's id as
permission, is labelled as the read-only list labels it, with no id shown, and is ticked when the role holds it; - a box disabled, never ticked, when the viewer may not give the permission and the role does not hold it. Held, it can be unticked, and says "You cannot give this permission back once it is removed.";
- "Save permissions", the primary button.
When the group offers nothing, the section says "This role's group offers no permissions to give; the app declares
in code which permissions each group offers" and shows no form. A refused or failed offer shows "The role's
permissions could not be read" with the seam's Message, and no form. Without the form, a post naming it gets the
framework's 400.
The handler checks the same conditions again. It reads the ticked ids and the loaded ids from the request's form,
never bound as a collection. A post carries two values for each permission the role holds, so the form's value count
limit, FormOptions.ValueCountLimit (1024 unless the app sets it), bounds the grants one save can carry: a post over
it is answered 400 before the page runs, and nothing is saved. That limit is the one an app raises for a role that
holds more than about 500 permissions. The handler calls IKitRoles.SetPermissionsAsync for the route's role, by the
name GetAsync answered. The outcome is one alert at the top of the section:
| Outcome | The alert | Then |
|---|---|---|
Done |
"Permissions saved: added 2, removed 1", the names added and removed under it, then each clause that applies: "1 permission sent was not given, as this role's group does not offer it"; that the change reaches this instance at once and the app's other instances when they are told, so until then they may still honour the old permissions (CacheConfirmed false); "this change was not recorded". Success, or Warn when any clause applies. |
The audit row roles.permissions-changed, its payload the names granted and revoked; then the role, its grants and its offer read again. |
Stale |
Warn: "Permissions changed since this page was opened; nothing was saved. The boxes now show the permissions the role holds." The last sentence shows only when the read after the save renders the boxes. | The role read again, so the boxes show the stored grants. |
Failed |
Danger, "Permissions may not have been saved": "The save failed, but it may have been stored before it failed. The boxes now show the permissions the role holds. If it was stored, no record says who changed it." The boxes sentence shows only when the read after the save renders them; the record sentence only when the app's IKitAudit records. A fault after the commit is answered Failed too, and no audit row is written. |
The role read again, so the boxes show what is stored. |
Unchanged |
Neutral: "This role already holds these permissions; nothing changed". When an id sent was not given, "Nothing changed", then that clause, in Warn. | Nothing read again. |
| Any other | Danger, "Permissions not saved", with the seam's Message, such as PermissionOutOfReach for a disabled box posted by hand. |
The boxes keep the ticks posted and the loaded ids posted; a disabled box stays unticked. |
The audit row is written with no cancellation, since the change is not undone. The read after a save never sets 404: a role it does not find, or a read it is refused, shows the save's alert above the empty state or the refusal, so the page still says whether the save landed.
Removing grants outside the group's offer
The permissions form cannot take away a grant its role's group may not hold, since it lists only the offer. Under the
form's conditions (CanManage, a role the viewer may edit, a page address KitHref.Local accepts), the Permissions
section renders one KitConfirm, role-clear-outside, posting to the page's own address with #permissions. It
renders whatever the role holds, so a post from a page another administrator made stale is answered, not refused.
Its opener, "Remove these 3" ("Remove 1 permission" for one, the confirm button's words), a Default button, follows
the "Not offered to this role's group" list when the role's group is a declared group and the count is above zero. The
count is the grants listed that the framework's removal would take, those HeldPermissionsAsync marks Removable.
Two kinds of NoDeclaration grant are listed but kept, so never counted: an undeclared menu root, which the menu
needs, and a name the database's collation matches to a declaration allowing the group, which the permission check
honours. For a role whose group is not declared, the opener does not show; the section's alert says the fix is the
declaration, as for a group that was only renamed. While the opener shows, each grant listed that the removal keeps
has a second line under its class, muted: "Kept when the others are removed". The grants without that line are the
ones the count names.
The confirm says the permissions are not ones the role's group may hold, that users holding the role lose them at
once where they still gave access, and that the audit record keeps their names, or, when the app's IKitAudit does
not record, that no record will; for one grant its title, body and button are in the singular. It lists the grants it
removes by the list's own labels: the description, else the name in the mono face, else the id the grant names. Its
button, the one Danger, reads "Remove 3 permissions". Without the form's conditions no confirm renders, and a post
naming it gets the framework's 400.
The handler checks the same conditions again and calls IKitRoles.RemoveGrantsOutsideOfferAsync for the route's
role, by the name GetAsync answered. The outcome is one alert at the top of the section:
| Outcome | The alert | Then |
|---|---|---|
Done |
"Removed 3 permissions this role's group may not hold", the names and missing ids removed under it. The count is the framework's: Revoked and RemovedMissingIds together. Then each clause that applies: that the other instances may still honour the old permissions (CacheConfirmed false); "this change was not recorded". Success, or Warn when a clause applies. |
The audit row roles.outside-grants-removed, its payload Revoked and RemovedMissingIds; then the role read again. |
Unchanged |
Neutral: "Nothing was removed: this role now holds no permission outside its group's offer that can be removed." The grants changed since the page was opened. | The role read again. |
Failed |
Danger, "Permissions may not have been removed": "The removal failed, but it may have been stored before it failed. The list now shows the permissions the role holds. If it was stored, no record says who removed them." The role is read first: the second sentence shows only when that read renders the list of grants outside the offer, and the last only when the app's IKitAudit records. No audit row is written. |
The role read again. |
GroupNotFound |
Warn, with the seam's Message: "Nothing was removed: this role's group is not a declared permission group." |
Nothing read again. |
| Any other | Danger, "Permissions not removed", with the seam's Message. |
Nothing read again. |
As after a save, the read after a removal never sets 404, and the audit row is written with no cancellation.
Deleting a role
With CanManage set and a role the viewer may edit (CanEdit, and not held by the viewer), the Users section
renders one KitConfirm, role-delete, posting to the page's own address with #users. It renders whether or not a
user holds the role, so a delete posted from a page opened before the role gained a user is answered in words.
With no holder, the section's action region holds its opener, "Delete role", a Default button. With holders, the
section's line says how to make deleting possible, "Held by 12 users in all; remove the role from them before deleting
it" ("from that user" for one), and no opener shows. The count is every holder in every tenant, so the users list
may show fewer.
The confirm, titled "Delete Clerk?", says the role and its 3 permissions are removed, that this cannot be undone from
here, and that the audit record keeps their names, or, when the app's IKitAudit does not record, that no record
will; for one permission it is in the singular, and a role holding none says so. Its button, the one Danger, reads
"Delete role". Without CanManage, or for a role the viewer may not edit, no confirm renders, and a post naming it
gets the framework's 400.
The handler checks the same conditions again and calls IKitRoles.DeleteAsync for the route's role, by the name
GetAsync answered, so a route naming the role in another letter case deletes the stored role. The outcome is one
alert:
| Outcome | The alert | Then |
|---|---|---|
Done |
"Role Clerk deleted", the names and missing ids removed under it, then each clause that applies: that the other instances may still honour the role's permissions (CacheConfirmed false); "this change was not recorded", when the row was not written or the app's IKitAudit does not record. Success, or Warn when a clause applies. |
The audit row roles.deleted, its payload the role's group, RemovedPermissionNames and RemovedMissingIds. The role is not read again: the page answers 200 with only its header, the role's name as its title and "All roles" in its line, then "History" with a HistoryHref, and the alert. |
Failed |
Danger, chosen by what the read after the delete found. The role, by its id: "Role not deleted", "The delete failed; the role is still stored, as this section shows.", with "You can delete it again." while the opener shows. No role, or a role of another id under the name: "Role no longer stored", "The role is gone, though the delete reported a fault.", then "The role shown here is a new one under its name." when there is one, and "No record says who deleted it." when the app's IKitAudit records. A read refused: "Role may not have been deleted", "The delete failed, but it may have been stored before it failed.", then "If it was stored, no record says who deleted it." when the app's IKitAudit records. No audit row is written. |
The role read again first; a role no longer found shows the alert above "Role not found", with 200. |
| Any other | Danger, "Role not deleted", with the seam's Message; for RoleInUse: "At least one user holds this role, in this tenant or another, so it was not deleted." |
The role read again. |
Except after Done, the alert sits at the top of the Users section; when the read after the delete finds no role or
is refused, it follows the header, above "Role not found" or the refusal. The audit row is written with no
cancellation, since the delete is not undone.
A deleted role's name can come back with grants. Once a role of the name exists again, whether the app's seed or an
administrator creates it, the framework's permission seed gives it, each time the seed runs (an app runs it at
start-up), every grant whose permission names it in AllowedRoles and that its group may hold; remove the name from
those declarations too. The delete ends no session: a role created again under the name gives its grants to any
open session whose role claims still carry the name, until that session's stamp is next checked. An app that does not
end sessions on a role change lets that interval pass before reusing a name.
The new-role screen
KitRoleCreate creates a role through IKitRoles.CreateAsync. The app writes the page; its route is the roles list's
CreateHref:
@page "/admin/new-role"
@using Microsoft.AspNetCore.Authorization
@using Solhigson.Framework.Web.Attributes
@using Solhigson.Framework.Web.Authorization
@attribute [Permission("roles.view")]
@inject IAuthorizationService Authorization
@if (canCreate is bool create)
{
<KitRoleCreate ListHref="~/admin/roles" DetailHref="~/admin/roles/{name}" CanCreate="@create" />
}
@code {
private bool? canCreate;
[CascadingParameter]
private HttpContext? HttpContext { get; set; }
protected override async Task OnInitializedAsync()
{
var decision = await Authorization.AuthorizeAsync(HttpContext!.User, PermissionPolicy.For("roles.create"));
canCreate = decision.Succeeded;
}
}
The screen renders once canCreate is decided, so the form a post names is there when the post is handled.
Put the page at an address no role's page can have. A literal segment outranks a route value, so a page at
/admin/roles/new would take the place of the page of a role named "new".
The page refuses framing, as the role page does, so no other site can lay the form that creates a role under a
decoy: the app sends X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on it, since the
component sets no header.
| Parameter | Required | What it does |
|---|---|---|
ListHref |
Yes | The roles list, a path on this site: the header's "All roles" link. A ListHref that KitHref.Local refuses, or none, throws when the screen renders. |
DetailHref |
Yes | A role's page, a path on this site holding {name}, as the list's DetailHref. KitRoleLinks.For builds the link to the new role's page. A DetailHref without {name}, or one KitHref.Local refuses with a name in place, throws when the screen renders. |
CanCreate |
No | Whether the viewer may create roles. False unless set. Gate it with the app's own permission check, as CanManage on the role page. |
The header is "New role", with "All roles" in its line. Without CanCreate, a Danger alert says the viewer may not
create roles, the groups are not read, and no form renders. With it, the screen reads every stored group
(GroupNamesAsync). A refusal of that read is its Danger alert. With no stored group, an alert says "Roles need a
group, and this app has none yet; the app's setup adds them." Neither renders a form. Otherwise the screen holds one
form, role-create, which posts to the page's own address, its query kept:
- "Name", required, with
maxlengththe framework'sMaxRoleNameLength, 64. - "Group", a required select of every stored group. It opens on an empty "Choose a group" option, so no group is chosen by its place in the list. Under it: "This screen cannot change the group later."
- "Create role", a Primary submit.
Where no form renders, a post to it answers the framework's 400 and calls nothing. The select lists every group, not
only the ones the viewer may create in: whether they may is the framework's answer, from the app's rules'
MayCreateRoleAsync, and its refusal shows beside the group. An app whose rules never allow a create shows a form
that always refuses; leave CanCreate false there.
The post handler checks CanCreate and a stored group itself, before any call, so a path to it that is not the form
creates nothing. A post of the empty option shows "Choose a group for the role." beside the group, with no call.
A new role holds no permission. After a create done, the screen records roles.created when IKitAudit records,
with no cancellation: the row is keyed by the role's id and named by its name, and its payload is GroupName, the
group as stored. It then shows one alert above the form, now empty:
| The new role | The alert |
|---|---|
Inside the viewer's own Grant answer (CanEdit), in a declared group |
Success: "Role Ops created.", with "Set its permissions", a link to the role's page. |
| Outside that answer | Warn: "Role Ops created; an administrator who may grant this role must set its permissions." There is no link, since the viewer may not set them. |
In a group the app does not declare (GroupKnown false) |
Warn: "Role Ops created; its group is not a declared permission group, so it can be given no permission until the app declares the group." Outside the viewer's Grant answer too, it adds "; an administrator who may grant this role must set its permissions" after that. There is no link, since the role page offers it nothing. |
When the audit row was not written, the alert adds "this change was not recorded" and is Warn. A name that holds a
literal %2F, with {name} in the address's path, gets no link, as on the roles list. A seam of the app's own that
answers Done with no Row gets a Warn alert that the role was created and not recorded, since no id keys the row,
and the guard writes the Error KitUserSeamDoneUnnamed (see The app's sessions and
notices). The framework answers Done for a role it stored even when the request is
cancelled after the save, so the row is written.
Each refusal is said in its place:
| Outcome | Where |
|---|---|
InvalidName, RoleExists |
Beside the name. |
GroupNotFound, GroupOutOfReach |
Beside the group. GroupOutOfReach says "You may not create a role in this group; choose another." |
Failed |
A Danger alert above the form, "The role may have been created": "Something went wrong as it was saved. Look for it in the roles list before you create it again." When the app's IKitAudit records, it adds "If it is there, no record says who created it." |
IdentityFailed, InTransaction, NoRules, ActorRefused and any other |
A Danger alert above the form, "Role not created". |
Each keeps the typed name and the chosen group. Nothing is recorded. The screen writes no log line of its own but the guard's above; the seam's lines are in The roles seam's log lines.
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 the Blazor router 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, before its first ?
or #, 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:
- The header, "Users", with "New user" as its primary link when
CreateHrefis set and the page has rows. - One band: the search first, then the filters.
- 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.
- 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 thesearchedsearch, 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" HistoryHref="~/admin/audit" 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. |
HistoryHref |
no | The audit page's path on this site, alone, with no query or fragment (see The audit screen). With it, the header's line ends with two quiet links, a gap apart, each value escaped and with no day, so the list reads all time. "History" reads the user's records by their id alone, with no type: ?id=<the user's id>, since audit capture stamps a row of the app's user class with that class's name, such as AppUser, while this page records under User, and an id-only read finds both. With an id that is not unique across types, the history also holds other subjects stored under the same id, each shown with its type. "Activity by this person" reads what they did, by their id as the actor: ?actor=<the user's id>. A refusal's header has neither. Without it no link renders; a value KitHref.Local refuses, or one holding a query or a fragment, 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:
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, then, with
HistoryHref, "History" and "Activity by this person".A Warn alert, "Changes here leave no audit record", when
CanManageAccessorCanConfigureis set and the app'sIKitAuditdoes not record (see Recording changes).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."
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.
Two-factor (id
two-factor), only whenTwoFactorAvailable: "On." or "Off."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:
CanManageAccessis 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:
- It calls
IKitSessions.EndAsyncwhen the result saysEndSessions. - It calls
IKitUserNotices.PasswordLinkNeededAsyncwhen the result saysNeedsPasswordLink. - It records
users.enabledorusers.disabledwhenIKitAuditrecords. The payload isEnabled,SessionsEndedandPasswordLinkSent.
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 answeredUnchangedstill callsEndAsync. 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
opthe form never renders: a Warn alert, and nothing changes.
Ending a lockout and sending a password link
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:
AddSolhigsonTwoFactoron the identity registration. Without it,TwoFactorAvailableis false and no confirm renders.- Identity's EF
UserStore, saving through the app's context withAutoSaveChangeson. Without it, every reset answersFailed, with an Error at stepReset. - The counter store
AddSolhigsonTwoFactorregisters: the framework's Redis store, unless the app registers its ownICounterStore. Building the Redis store needs anIHostEnvironment, 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 stepTwoFactorCodeCap. 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:
CanManageAccessis set.TwoFactorAvailableis 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:
- It calls
IKitSessions.EndAsync, since the reset rotated the security stamp. - It calls
IKitUserNotices.TwoFactorResetAsyncwith whether a password was removed. The notice carries the link to set a password, then to enrol again. - It records
users.two-factor-resetwhenIKitAuditrecords. The payload isPasswordRemoved,SessionsEndedandPasswordLinkSent.
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:
CanConfigureis 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:
- One hidden
loadedfield for each role the user held when the page was rendered. - 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
rolefor each roleIKitUsers.GrantableRolesAsyncoffers and each role the user holds, ordered by name, ticked when held. - When
RoleChangeDisablesis 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). - 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:
- It calls
IKitSessions.EndAsync, since the change rotated the security stamp. - It calls
IKitUserNotices.AccessChangedAsyncwith the names granted and revoked and whether the user was disabled. - It records
users.roles-changedwhenIKitAuditrecords. The payload isGranted,Revoked,Disabled,SessionsEndedandNoticeSent.
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.
CanConfigureis 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:
- It calls
IKitSessions.EndAsync, since the change rotated the security stamp. - It calls
IKitUserNotices.EmailChangedAsyncwith 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. - It records
users.email-changedwhenIKitAuditrecords. The payload isPreviousEmail,SessionsEndedandNoticeSent. 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 for a user without two-factor, needing CanConfigure only; a user enrolled in two-factor still needs the
second factor after the reset while the app's two-factor is on, and CanManageAccess as well removes that limit, since
the two-factor reset removes the factor. Only keeping AllowEmailChange off guards that path. Giving the two
permissions to different roles does not, and neither does a reset that asks for a confirmed address: an email change
leaves the new address unconfirmed, but whoever reads it can confirm it through a confirmation the app sends without the
user's own sign-in (Identity's default UI has an anonymous ResendEmailConfirmation page), or through an external
sign-in that matches accounts by address. Where the app's sign-in sends no password reset by email and no external
sign-in matches accounts by address, 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; an audit write's line carries the event's
entity type and id instead, since the role page writes its rows through the same guard, and the line of a change done
that names nothing carries no id at all:
| 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. |
KitUserSeamAuditFailed |
Error | The app's {Seam}.{Member} threw {ExceptionType} for {Action} on {EntityType} [{EntityId}]; it counts as false. | The app's audit seam broke its contract, which forbids a throw. Read the app's own log for the exception; the row was not written. |
KitUserSeamDoneUnnamed |
Error | The app's {Seam}.{Member} answered Done with no {EntityType} in it, so {Action} was not recorded. | The app's own seam, registered in place of the package's, answered a change done without naming what it changed, so the screen has no id to key the audit row by. Fix the seam to answer the row; find the change in the list meanwhile. |
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:
- "Email address", required.
- "Phone number", a text field with the telephone keypad.
- The fieldset "Roles", its legend carrying the required mark, with a box for each role the viewer may grant.
ExtraFields.- "No password is set here; the user chooses one from a password link."
- "The user starts disabled, and cannot sign in until someone enables the account.", when the framework's
UserAdministrationOptions.NewUserStartsDisabledis on. It is on unless the app turns it off. - "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:
- It calls
IKitUserNotices.PasswordLinkNeededAsyncfor the new id. - It records
users.createdwhenIKitAuditrecords. The payload isRoles(the names given, as stored),DisabledandPasswordLinkSent. 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.
The gallery
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.
Links
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.
A click that changes the scheme the page draws fades its colours from the old scheme to the new: before it changes
data-theme, kit.theme.js puts kit-theme-fading on the <html> element, under which every element's background,
text, border, outline, underline, accent, fill, stroke and shadow colours, and those of its ::before, ::after and
::placeholder, transition over --kit-d-theme (320ms) on --kit-ease-theme, and nothing else moves; the class goes
after --kit-d-theme-hold (380ms). A click that leaves the drawn scheme as it was, Dark under a dark system with no
choice, fades nothing. The first paint, the page put back in line with the cookie, and a change of the system's own
theme under no choice swap at once; under prefers-reduced-motion both tokens are 0ms, so a click swaps at once
too. For the hold the fade replaces a kit component's own transition, and a transition an app sets in @layer app
wins over the fade.
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 | Versions 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. |
-
net10.0
- Solhigson.Framework.Core (>= 10.29.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
10.4.0: the audit trail screens (Solhigson.Admin.Components, Solhigson.Admin.Auditing). The reader seam: IKitAuditReader, which AddSolhigsonAdmin registers scoped over the framework's IAuditTrailReader<TContext> for the context it is given, as it registers IKitAudit, is how the audit screens read the audit trail (Available; SearchAsync of a KitAuditSearch, answering a KitAuditPage of KitAuditRow; GetAsync of a record's id and created key, answering a KitAuditLookup of a KitAuditRecord; each answer carrying a KitAuditOutcome, Done, NotAvailable, ActorRefused, NotFound or Failed, and KitAuditMessages.For's sentence). It refuses a viewer who is not signed in before anything is read, reads the time once from the registered TimeProvider and resolves one window from the viewer's days in their zone through the framework's AuditTrailWindow, passes every filter and the cursor, answers NotAvailable with no query when no reader resolves or the context does not map AuditTrail, and throws nothing but the caller's cancellation; a fault's line names the filters set, never their values. A row's Linkable, ActorLinkable and ActorAttempted say whether a link may carry its entity id or its actor id, so text a sign-in caller typed never reaches a link, and a name a caller gave on a security event is marked as attempted. People are named for the viewer: a name a row stores shows to every viewer; an id it stores with no name is looked up in one UserAdministration.ResolveDisplayNamesAsync call a page or a record, and shows as the user's name only when the viewer's scope admits the user, else as a fragment of the id; a subject is looked up only on a user's entity type under an allow-listed action, KitAuditOptions' UserEntityTypes (User by default, beside the identity's own user class) and ResolvedSubjectActions (the users.* actions by default); a record about a user the viewer may not reach is Restricted and carries no changes, no snapshot and no address, a record's address is withheld unless the lookup names its actor for the viewer, while a record with no actor id keeps its address, which ShowIp shows to every viewer unless the record is Restricted, and a failed lookup sets NamesUnavailable. With no user-administration rules registered nothing is looked up or restricted, so the audit page's permission belongs only to roles that may see every user. KitAuditLabels gives the package's 15 audit actions a label and a verb phrase (For, Sentence, TypeInWords), so a record reads "Ada Obi changed the roles of Jane Doe", and any other action reads as the framework's AuditDisplay labels it; KitAuditEvent.SettingEntityType names the settings screen's entity type. The audit list: KitAuditList, which an app places on its own page with DetailHref (holding {id} and {created}) and an optional TimeZone, lists the records of one window newest first, a page at a time: the header says the window in the viewer's zone, with Today, Last 7 days and Last 30 days; a GET filter bar holds the days and the category, and behind More filters the action, the subject type, the subject id and the person (the query names from, to, category, action, type, id, actor and cursor), each matched exactly as stored; the table shows when, what (the action's label, linking to the record), the subject and the person, a subject linking to its history and a person to their activity only where the row allows it; a search naming a subject or a person and no day reads all time. The audit entry page: KitAuditDetail, on a page with the record's id and created key in its route, taking Id, Created, ListHref, an optional UserHref and TimeZone, and ShowIp (false unless set), shows one record: its sentence as the title, when it was written in the viewer's zone, the facts (the category, the action, the subject, the person, the source and, with ShowIp, the address), What changed and Recorded values, a masked value reading Hidden and a payload not in the stored shape shown as text in a block that scrolls inside itself; nothing in a record is ever markup; a record not found answers 404, and the page must not stream. The history links: KitSettingsEditor, KitUserDetail and KitRoleDetail gain HistoryHref, the audit page's path, with which each setting's row ends with a History link, the user page's header gains History and Activity by this person, and the role page's header gains History, kept after a delete, each to the audit list with no day; a HistoryHref that KitHref.Local refuses, or that holds ? or #, throws before any read, and with none set nothing renders. To adopt: add two pages (the audit list, a record by id and created key), each with its route and [Permission]; the record page must not stream; map AuditTrail in the context passed to AddSolhigsonAdmin; the audit trail is one trail for the whole app, so the permission decides who reads it; a name is looked up only for users the viewer's scope admits, while a name stored on a record shows to every viewer; a record about a user the viewer may not reach shows no values; an app that captures its user class adds "securitystamp" to AuditCaptureOptions.AdditionalSensitiveNamePatterns, through a pre-populated AuditCaptureOptions singleton the framework's registration leaves in place, since the defaults do not mask SecurityStamp, which the record page would show ("securitystamp" masks the secret and nothing else, where a plain "stamp" would also mask any Timestamp column); rows captured before the pattern keep the raw stamp, so an app that has captured its user class adds the pattern, then rotates every user's security stamp (UserManager.UpdateSecurityStampAsync) before it grants the audit permission, which ends every open session at the next stamp check; an app never opts Identity's user-token, user-login or user-claim types into capture, since their values are credentials no pattern masks and their records are not restricted; add any other user class name, beside the identity's own, to KitAuditOptions.UserEntityTypes and its own safe user actions to ResolvedSubjectActions; pass TimeZone; ShowIp is off by default; pass HistoryHref to the settings, user and role pages. The README lists each log line the reader seam writes (KitAuditReaderNoActor, KitAuditReaderSearchFailed, KitAuditReaderGetFailed, KitAuditReaderUnresolved) and each line the screens' reads cause under AuditTrailReader, UserAdministration and the users seam, its level and what to do; the screens write no line of their own. The kit: KitNotice, given a KitNoticeMessage (KitNoticeMessage.Landed or NotLanded, a blank text or step throwing), says a post's answer in one message at the foot of the screen that rises in, stays (--kit-notice-dwell, --kit-notice-long-dwell) and leaves on its own, in CSS alone, and is drawn only inside KitShell, which tells it to a screen reader through two live regions that kit.notice.js fills; KitButton gains Answer (KitButtonAnswer: None, Landed, a ring in the success colour, or Failed, a sideways nudge), drawn on the render that answers a post, changing neither the button's colour, text nor size, and still under reduced motion; kit.forms.js removes every notice and both answer classes as it marks a post's submitter busy, so the next answer plays; KitFilterBar gains Enhance, true unless set, false for a bar holding a field named after a form's own member, such as action, which then submits as a plain form; kit-facts is the facts list the audit record page and the user page share; kit.manifest.json gains the kit-audit, kit-facts and kit-notice names, the kit-btn-landed, kit-btn-nudged, kit-gallery-notices, kit-role-history and kit-user-history classes, the component token --kit-audit-raw-height (the raw payload block's height, the measure unless set) and the tokens --kit-d-flash, --kit-flash-spread, --kit-flash-ring, --kit-flash-ring-end, --kit-d-nudge, --kit-nudge-1, --kit-nudge-2, --kit-nudge-3, --kit-d-notice, --kit-d-notice-leave, --kit-notice-rise, --kit-notice-dwell, --kit-notice-long-dwell, --kit-z-skip and --kit-z-float, and loses none; every new duration token is 0ms under reduced motion. Changes for a 10.3.0 app: AddSolhigsonAdmin also registers IKitAuditReader and, when the app registers no TimeProvider, TimeProvider.System, each kept when the app registered it first; KitHead also links kit.notice.js, with the page's nonce as its other scripts; KitShell renders two empty, visually hidden live regions, a status and an alert, after its main region on every page; the user page's facts list also carries the kit-facts class, its kit-user-facts class kept; and the header line of the user and role pages, and of the new-user and new-role screens, is a flex row that wraps, spaced by its gap, so a back link after a wrapped email or group takes its own line. Minor bump: every type and member is new but for those changes. Depends on Solhigson.Framework.Core 10.29.0 or later. 10.3.0: the role and permission screens (Solhigson.Admin.Components, Solhigson.Admin.Roles). The roles seam: IKitRoles, which AddSolhigsonAdmin registers scoped over the framework's RoleAdministration as it registers IKitUsers, is how the role screens read and change roles (ListAsync, GetAsync, HeldPermissionsAsync, OfferedPermissionsAsync, SetPermissionsAsync, RemoveGrantsOutsideOfferAsync, CreateAsync, DeleteAsync, PermissionsAsync, GroupNamesAsync; with KitRolePage, KitRoleLookup, KitRoleRow, KitHeldPermissions, KitOfferedPermissions, KitPermissionPage, KitRoleResult and KitRoleAudit's roles.* actions, GroupNamesAsync answering the 10.2.0 KitRoleNames); it reads the acting user by the users seam's rule, adds no rule of its own and throws nothing but the caller's cancellation. KitRoleLinks.For builds every link to a role from the app's template, and a role's page passes its route value as given, never decoded again. The roles list: KitRolesList, which an app places on its own page with DetailHref (holding {name}) and an optional CreateHref and UsersHref (holding {role}), lists every stored role by group, then name, with a GET filter by group: the name linking to the role's page, marked Yours or View only, the group, the users holding it in every tenant with a link to the ones the viewer manages, and its grants. The role page: KitRoleDetail, on a page with the role's name in its route, taking RoleName, ListHref, an optional UsersHref and CanManage, says first whether the viewer can change the role and why not, then shows what the role holds, the grants its group offers by top permission and those outside the offer with their class in words, and how many users hold it; a role not found answers 404, and the page must not stream. With CanManage, for a role the viewer may edit and does not hold: the permission editor, one form with a box for each permission the role's group offers, a box disabled where the viewer may not give the permission and the role does not hold it, so a viewer adds only permissions it holds unless the app's rules answer its Grant with All, saving through SetPermissionsAsync, refused as stale when the role's grants changed since the page loaded, and recorded as roles.permissions-changed; the clearing of out-of-group grants, a confirm that removes the grants the group may not hold that the framework marks removable (HeldPermission.Removable), recorded as roles.outside-grants-removed; and delete, a confirm opened only while no user in any tenant holds the role, answered RoleInUse otherwise, removing the role and its grants, recorded as roles.deleted. A save, a removal or a delete answered Failed may have been stored: the page reads the role again and says what it found, and no audit row is written. A post carries two values for each permission the role holds, so FormOptions.ValueCountLimit (1024 unless the app sets it) bounds a save at about 500 held grants, a longer post answered 400 with nothing saved. Role creation: KitRoleCreate, with ListHref, DetailHref and CanCreate (false unless set), creates a role holding no permission, its name of at most 64 characters, in the stored group the viewer chooses, where the app's rules' MayCreateRoleAsync allows it, which refuses unless the app writes it; it records roles.created and links to the new role's page, or says that an administrator who may grant the role must set its permissions, or that its group is not declared; a Failed create says the role may have been created, so look it up before creating it again. The permissions list: KitPermissionsList, with an optional RoleHref, lists every stored permission in the role editor's order, with its parent, the groups its declaration allows (a Warn pill for one offered to no group) and the roles holding it, with a GET search and, with permission groups registered, an offered-to-no-group filter. The role page and the new-role page refuse framing: the app sends X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on them, and the components set no header. A deleted role's name can be created again, and that role then gets the seed's AllowedRoles grants that its group may hold and matches any open session still carrying the role claim until its stamp is next checked; a role the app seeds leaves the seed before it is deleted. The README lists each log line the role screens write (the seam's KitRolesNoActor and KitRolesFailed, the guard's KitUserSeamAuditFailed and KitUserSeamDoneUnnamed, the audit seam's, and the framework's lines under RoleAdministration and Solhigson.Framework.PermissionGroups that the screens cause), its level and what to do, beside the role_administration counter on the meter Solhigson.Framework.Identity. The kit: KitButton gains BusyText, the doing word a submit button reads with three working dots while its post is out, and kit.forms.js now holds a form whose kit button is busy, so a second submit of it is not sent until the answer is on the page or --kit-btn-busy-dwell (20s) passes; a theme pick cross-fades the colours (--kit-d-theme, --kit-d-theme-hold); a page change inside KitShell slides in from the side it came from (kit.nav.js and kit.core.js, which KitHead links with the page's nonce; --kit-d-enter); the rail's marker glides to the current item where the browser can anchor it (--kit-d-glide); every such motion stops under reduced motion; kit.manifest.json gains the kit-role, kit-roles, kit-permissions, kit-enter, kit-rail-marker and kit-theme-fading names and the new tokens, and loses none. Changes for a 10.2.0 app: an audit seam that throws now writes KitUserSeamAuditFailed (event id 3), naming the event's entity type and id, in place of KitUserSeamFailed (event id 2), so an alert on the old line stops seeing audit throws; AddSolhigsonAdmin also registers IKitRoles, kept when the app registered it first; a # in the users list's DetailHref now ends its path as a ? does; and the email change's limits no longer offer gating a reset on a confirmed address, since whoever reads the new address can confirm it through a confirmation sent without the user's sign-in (the anonymous ResendEmailConfirmation page of Identity's default UI) or an external sign-in matching accounts by address: where the app's sign-in sends a reset to an address it has not confirmed, only keeping AllowEmailChange off guards an address takeover, so an app that relied on that gate turns AllowEmailChange off. Minor bump: every type and member is new but for those changes. Depends on Solhigson.Framework.Core 10.29.0 or later. 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 for a user without two-factor, needing CanConfigure only; a user enrolled in two-factor still needs the second factor after the reset while the app's two-factor is on, and CanManageAccess as well removes that limit, since the two-factor reset removes the factor. Only keeping AllowEmailChange off guards that path. Giving the two permissions to different roles does not, and neither does a reset that asks for a confirmed address: an email change leaves the new address unconfirmed, but whoever reads it can confirm it through a confirmation the app sends without the user's own sign-in (Identity's default UI has an anonymous ResendEmailConfirmation page), or through an external sign-in that matches accounts by address. Where the app's sign-in sends no password reset by email and no external sign-in matches accounts by address, 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.