@jimhoyd/urlcode-admin 0.1.0-alpha.1

package/UX-REVIEW.md

@@ -0,0 +1,61 @@
+# Administration UX review
+
+This review covers the HTML console, its source routes and focused regression
+checks. It is a usability and accessibility pass, not WCAG certification or an
+independent security assessment. The console uses shared URLCode UI primitives;
+account terminology, permissions, workflows and copy remain in this repository.
+
+| Screen or concern | Finding | Change |
+| --- | --- | --- |
+| Shared shell | The skip link stopped before the sidebar; the visible title was an h2 below a hidden h1. | One visible page h1 and a focusable content target after navigation. Native mobile navigation stays collapsed until opened. Security response headers and theme scripts are preserved. |
+| Overview | Exact-value tables could overflow and an empty event list gave no explanation. | Keyboard-focusable table regions and explicit empty activity feedback. Metric links retain permission filtering. |
+| Users | Lock/revoke controls had the same visual weight as search; identifiers and dates were dense. | Destructive button treatment, concise UTC dates with exact machine-readable timestamps, masked identifiers, expandable actions, and retained filter selections. Default search fields keep advanced filters closed. |
+| Account details | Notes, session revocation and identifier reveal competed with account facts; recovery links appeared when no delivery integration existed. | Clear fact grid, section navigation, expandable sensitive actions, note guidance, empty states, and recovery links gated by actual availability. Consent records and user content remain escaped. |
+| Roles | Ungrouped role/grant lists and assignment fields obscured the read-only policy boundary. | Permission table plus a separate assignment card, descriptive empty grants and explicit read-only configuration explanation. |
+| Sessions | Long prose lists mixed identity, dates and immediate revoke forms. | Filter card, table with masked accounts and readable timestamps, empty results, expandable destructive actions and a separate revoke-all section. |
+| Audit | Submitted filters were not retained, labels exposed raw parameter names and export competed with filtering. | Persistent input values, human-readable labels, explicit UTC format, scrollable event table, empty state, and separate export disclosure. |
+| Health | Raw enum alerts and missing empty states made a configured-but-quiet service look unfinished. | Grouped facts, status badges, plain-language alert copy and explicit absence of reported alerts. Unknown sender/provider observations remain unknown. |
+| Support cases | All mutation forms appeared at once, and action input was free text. | Case cards with expandable notes/closure/approval, a constrained action select and empty queue feedback. Two-person authority checks are unchanged. |
+| Registration | An empty queue rendered no content. | Explicit empty queue feedback and a separate invitation card when delivery is configured. |
+| Account operations | Every destructive operation showed a full form immediately. | Grouped methods and expandable action cards; password invalidation, deletion and method removal use destructive styling. Existing typed confirmations, reasons and notification gates remain required. |
+| Manual recovery | Empty lists and long identifiers weakened hierarchy. | Explicit empty state, bounded evidence cards, readable identifiers, grouped creation and destructive approval styling. Evidence is still a human procedure, never automatic proof. |
+| Completed mutations | Confirmation pages left no clear next step. | Status feedback and a return link to overview or users. |
+| Copy ownership | New console text could not be translated without extending auth's nearly full catalogue. | Admin owns a separate bounded catalogue and a presentation factory that composes it with existing auth copy, without raising shared catalogue limits. |
+
+## Verification
+
+`npm run verify` passes 36 tests, including existing authorization, CSRF, freshness,
+notification, recovery, export and HTTP integration regressions. Added checks cover
+all principal console pages sharing one h1 and the skip target, preserved audit
+filters, meaningful empty states, unavailable recovery-link omission, destructive
+session forms retaining CSRF/reason fields, and admin-owned translation overrides.
+
+The final reviewed-package browser pass must additionally check desktop and narrow
+layouts, keyboard focus, mobile navigation, light/dark/system themes, long labels,
+empty/populated tables and provider-dependent screens. Typeface, palette, control
+sizing and theme behavior are supplied by URLCode UI and need verification at the
+exact integrated package revision. No live email/OIDC provider verification,
+comprehensive screen-reader audit or production data/soak validation is claimed.
+
+Error responses still use the shared auth failure renderer to preserve its
+redaction and security behavior. JSON schemas and authority decisions are
+unchanged. Historic method/activity timestamps remain unknown rather than invented.
+
+## Compact console follow-up
+
+The default templates now omit the overview's implementation instructions, repeated
+filter headings and obvious introductory paragraphs on sessions, audit, roles and
+health. The console shell has one page title without repeating the product and
+section above it. Users retain a visible masked-account caption and result count;
+the duplicate table caption remains available to assistive technology. Search,
+account setup and CSV export labels are shorter and owned by the admin catalogue.
+
+Template view fields remain available to project overrides. Empty states, errors,
+export limits, role-definition constraints, reason fields, destructive action
+consequences and fresh-authentication requirements are retained. Both primitive
+and kit rendering paths use the same compact screen templates.
+
+This follow-up passes all 61 admin tests, including both render paths, localization,
+strict CSP, immutable kit assets and all existing permission/mutation checks. The
+clean-project harness can now repeat installed-package acceptance with `--kit`;
+that run remains distinct from visual browser and accessibility review.

package/dist/admin-account.d.ts

@@ -0,0 +1,15 @@
+import type { ScreenOptions } from './admin-ui.ts';
+import type { ExtensionRequest, ExtensionInstance } from '@jimhoyd/urlcode/extensions';
+import { AuthHttp } from '@jimhoyd/urlcode-auth';
+import type { AuthPrincipal, AdminAccountService, AdminAccountDelivery } from '@jimhoyd/urlcode-auth';
+interface AdminAccountOptions {
+    service: AdminAccountService;
+    sendAccountAdministration?: (message: AdminAccountDelivery & {
+        signal: AbortSignal;
+    }) => Promise<void>;
+}
+export declare function createAdminAccount(options: AdminAccountOptions, http: AuthHttp, mount: string): {
+    enabled: () => boolean;
+    handle(request: ExtensionRequest, principal: AuthPrincipal, actorToken: string, render: ScreenOptions): Promise<Awaited<ReturnType<ExtensionInstance["handle"]>> | undefined>;
+};
+export {};

package/dist/admin-account.js

@@ -0,0 +1,82 @@
+import { escapeHtml, hiddenField as hidden, withDeadline } from '@jimhoyd/urlcode-ui';
+import { markup, screenResponse } from "./admin-ui.js";
+import { AuthHttp, AuthHttpError, csrfField, formField, hasPermission, jsonResponse, readFields, wantsJson } from '@jimhoyd/urlcode-auth';
+const actions = ['verify-email', 'force-password-reset', 'schedule-deletion', 'cancel-deletion', 'remove-passkey', 'remove-external', 'request-email-change', 'assign-roles', 'resend-verification'];
+export function createAdminAccount(options, http, mount) {
+    let callbacks = 0, batches = 0;
+    return { enabled: () => !!options.sendAccountAdministration, async handle(request, principal, actorToken, render) {
+            if (request.path.slice(mount.length) !== '/account-operations')
+                return;
+            if (!options.sendAccountAdministration)
+                throw new AuthHttpError(404, 'Not found');
+            if (principal.impersonatorId || !hasPermission(principal, 'auth.users.read'))
+                throw new AuthHttpError(403, 'Permission required');
+            const { presentation } = render, tr = (key, values) => presentation.text('adminOps.' + key.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase()), values), html = (key, values) => escapeHtml(tr(key, values)), csrf = http.token(actorToken);
+            const form = (action, ids, fields = '') => { const destructive = ['force-password-reset', 'schedule-deletion', 'remove-passkey', 'remove-external'].includes(action); return `<details class="ui-card${destructive ? ' ui-danger-zone' : ''}"><summary>${html('action.' + action)}</summary><form class="ui-form-grid" method="post" action="${escapeHtml(mount + '/account-operations')}">${csrfField(csrf)}${hidden('action', action)}${hidden('accountIds', ids)}${fields}${formField('reason', tr('reason'))}${formField('confirmation', tr('confirm', { value: action.toUpperCase() + ' ' + ids.split(',').length }))}<div class="ui-actions"><button${destructive ? ' class="ui-button-destructive"' : ''} type="submit">${html('action.' + action)}</button></div></form></details>`; };
+            if (request.method === 'GET' || request.method === 'HEAD') {
+                const ids = request.query.getAll('accountId');
+                if (ids.length > 1)
+                    throw new AuthHttpError(400, 'One account ID required');
+                const accountId = ids[0];
+                const screen = (view) => screenResponse(tr('title'), { name: 'admin/account-operations', view: view }, render);
+                if (!accountId)
+                    return screen({ bulk: { info: tr('bulkInfo'), form: markup(`<form class="ui-form-grid" method="post" action="${escapeHtml(mount + '/account-operations')}">${csrfField(csrf)}${formField('accountIds', tr('ids'))}<label>${html('actionLabel')}<select name="action"><option value="assign-roles">${html('action.assign-roles')}</option><option value="resend-verification">${html('action.resend-verification')}</option></select></label>${formField('roles', tr('roles'), 'text', 'off', false)}${formField('reason', tr('reason'))}${formField('confirmation', tr('bulkConfirm'))}<div class="ui-actions"><button type="submit">${html('apply')}</button></div></form>`) }, account: null });
+                const methods = await options.service.inspectAccountAuthentication({ actorToken, accountId, reason: 'Viewed account authentication methods' });
+                if (wantsJson(request))
+                    return jsonResponse(200, { ...methods, csrf });
+                const manage = hasPermission(principal, 'auth.users.manage');
+                const dates = (method) => `<span class="ui-muted">${escapeHtml(presentation.textSource('Added'))}: ${escapeHtml(method.added ? new Date(method.added).toISOString() : presentation.textSource('Not recorded'))}; ${escapeHtml(presentation.textSource('Last used'))}: ${escapeHtml(method.lastUsed ? new Date(method.lastUsed).toISOString() : presentation.textSource('Not recorded'))}</span>`;
+                const methodItems = methods.passkeys.map(method => `<li class="ui-card"><strong>${html('passkey')}</strong> <code>${escapeHtml(method.id)}</code> ${dates(method)} ${method.secondFactor ? html('secondFactor') : manage ? form('remove-passkey', accountId, hidden('credentialId', method.id)) : ''}</li>`).join('') + methods.external.map(method => `<li class="ui-card"><strong>${escapeHtml(method.provider)}</strong> ${dates(method)}${manage ? form('remove-external', accountId, hidden('externalId', method.id)) : ''}</li>`).join('');
+                return screen({ bulk: null, account: { idLabel: presentation.textSource('Account ID'), accountId, info: tr('info'), facts: [{ term: tr('password'), value: tr(methods.password ? 'yes' : 'no') }, { term: tr('totp'), value: tr(methods.totp ? 'yes' : 'no') }], methods: markup(methodItems), empty: !methods.passkeys.length && !methods.external.length ? presentation.textSource('No passkeys or external sign-in methods recorded.') : null, caseHref: mount + '/cases', caseLabel: tr('factorCase'), actions: markup(manage ? ['verify-email', 'resend-verification', 'force-password-reset', 'schedule-deletion', 'cancel-deletion'].map(action => form(action, accountId)).join('') + form('request-email-change', accountId, formField('email', tr('email'), 'email')) + form('assign-roles', accountId, formField('roles', tr('roles'))) : '') } });
+            }
+            if (request.method !== 'POST')
+                throw new AuthHttpError(405, 'GET, HEAD or POST required');
+            if (!hasPermission(principal, 'auth.users.manage'))
+                throw new AuthHttpError(403, 'Permission required');
+            const fields = readFields(request, ['action', 'accountIds', 'roles', 'email', 'credentialId', 'externalId', 'reason', 'confirmation']);
+            http.verify(request, fields);
+            const action = fields.action;
+            if (!actions.includes(action))
+                throw new AuthHttpError(400, 'Invalid account action');
+            const accountIds = (fields.accountIds || '').split(',').map(id => id.trim()).filter(Boolean);
+            if (fields.confirmation !== action.toUpperCase() + ' ' + accountIds.length)
+                throw new AuthHttpError(400, 'Typed confirmation must match action and count');
+            const base = { actorToken, accountIds, reason: fields.reason || '' };
+            let input;
+            if (action === 'assign-roles')
+                input = { ...base, action, roles: (fields.roles || '').split(',').map(role => role.trim()).filter(Boolean) };
+            else if (action === 'request-email-change')
+                input = { ...base, action, email: fields.email || '' };
+            else if (action === 'remove-passkey')
+                input = { ...base, action, credentialId: fields.credentialId || '' };
+            else if (action === 'remove-external')
+                input = { ...base, action, externalId: fields.externalId || '' };
+            else
+                input = { ...base, action };
+            if (batches >= 4 || callbacks >= 4)
+                throw new AuthHttpError(503, 'Account administration delivery busy');
+            batches++;
+            let operationId;
+            const deadline = Date.now() + 30000;
+            try {
+                const staged = await options.service.stageAccountAdministration(input);
+                operationId = staged.operationId;
+                for (const message of staged.deliveries) {
+                    if (callbacks >= 4 || Date.now() >= deadline)
+                        throw new AuthHttpError(503, 'Account administration delivery busy');
+                    callbacks++;
+                    await withDeadline(signal => { const pending = Promise.resolve().then(() => options.sendAccountAdministration({ ...message, signal })); void pending.finally(() => { callbacks--; }).catch(() => { }); return pending; }, Math.min(5000, deadline - Date.now()), 'Account notice delivery timed out');
+                }
+                const result = await options.service.completeAccountAdministration({ actorToken, operationId });
+                return wantsJson(request) ? jsonResponse(200, result) : screenResponse(tr('completed'), { name: 'admin/status', view: { alert: false, message: tr('affected', { count: result.affected }), href: mount + '/users', label: presentation.textSource('Back to users') } }, render);
+            }
+            catch (error) {
+                if (operationId)
+                    await options.service.cancelAccountAdministration({ actorToken, operationId }).catch(() => { });
+                throw error;
+            }
+            finally {
+                batches--;
+            }
+        } };
+}

package/dist/admin-audit-export.d.ts

@@ -0,0 +1,7 @@
+import type { AuthService } from '@jimhoyd/urlcode-auth';
+/** Complete bounded range export: never silently truncate a result or return partial unauthorized data. */
+export declare function exportAuditRange(service: AuthService, actorToken: string, query: URLSearchParams): Promise<{
+    from: number;
+    to: number;
+    events: Awaited<ReturnType<AuthService['listAudit']>>['events'];
+}>;

package/dist/admin-audit-export.js

@@ -0,0 +1,38 @@
+import { AuthHttpError, hasPermission } from '@jimhoyd/urlcode-auth';
+import { auditFilters } from "./admin-reporting.js";
+/** Complete bounded range export: never silently truncate a result or return partial unauthorized data. */
+export async function exportAuditRange(service, actorToken, query) {
+    if (query.has('after'))
+        throw new AuthHttpError(400, 'Range exports start at the beginning of the selected range');
+    const filters = auditFilters(query);
+    if (filters.from === undefined || filters.to === undefined)
+        throw new AuthHttpError(400, 'Choose both UTC range endpoints');
+    const from = filters.from, to = Math.min(filters.to, Date.now());
+    if (from > to)
+        throw new AuthHttpError(400, 'Choose a range that has started');
+    const events = [];
+    let after, bytes = 0;
+    const started = Date.now(), seen = new Set();
+    do {
+        const principal = await service.authenticate(actorToken);
+        if (!principal || principal.impersonatorId || !hasPermission(principal, 'auth.audit.read') || !hasPermission(principal, 'auth.audit.export'))
+            throw new AuthHttpError(403, 'Audit export permission required');
+        if (Date.now() - started > 5000)
+            throw new AuthHttpError(413, 'Choose a smaller audit range');
+        const page = await service.listAudit({ ...filters, from, to, limit: 100, ...(after ? { after } : {}) });
+        bytes += Buffer.byteLength(JSON.stringify(page.events));
+        if (events.length + page.events.length > 5000 || bytes > 4 * 1024 * 1024)
+            throw new AuthHttpError(413, 'Choose a smaller audit range');
+        events.push(...page.events);
+        after = page.next;
+        if (after) {
+            if (seen.has(after))
+                throw new AuthHttpError(503, 'Audit pagination unavailable');
+            seen.add(after);
+        }
+    } while (after);
+    const principal = await service.authenticate(actorToken);
+    if (!principal || principal.impersonatorId || !hasPermission(principal, 'auth.audit.read') || !hasPermission(principal, 'auth.audit.export'))
+        throw new AuthHttpError(403, 'Audit export permission required');
+    return { from, to, events };
+}

package/dist/admin-copy.d.ts

@@ -0,0 +1,64 @@
+import type { PresentationOptions, Presentation } from '@jimhoyd/urlcode-ui';
+/** Console copy belongs to admin. Shared UI contains no account or operator workflows. */
+export declare const adminCatalogue: Readonly<{
+    'adminUi.activityPeriod': "Last 30 days";
+    'adminUi.activityDetails': "View activity totals";
+    'adminUi.searchAccounts': "Search accounts";
+    'adminUi.searchPlaceholder': "Email, name or account ID";
+    'adminUi.createAccount': "Create account";
+    'adminUi.sendSetup': "Send setup link";
+    'adminUi.exportPage': "Export page (CSV)";
+    'adminUi.exportAll': "Export all (CSV)";
+    'adminUi.chartDescription': "Thirty UTC days of sign-ups, sign-ins and failed sign-ins. Failed sign-ins use a dashed line. Exact values follow in the daily table.";
+    'adminUi.noSessions': "No active sessions match these filters.";
+    'adminUi.noAudit': "No audit events match these filters.";
+    'adminUi.noCases': "No support cases to review.";
+    'adminUi.noRegistrations': "No registration requests are waiting for approval.";
+    'adminUi.noNotes': "No administrator notes yet.";
+    'adminUi.noActivity': "No account activity recorded.";
+    'adminUi.noAlerts': "No alerts reported.";
+    'adminUi.noMethods': "No passkeys or external sign-in methods recorded.";
+    'adminUi.noRecovery': "No manual recovery cases to review.";
+    'adminUi.noGrants': "No additional permissions";
+    'adminUi.noTerms': "No consent record is stored for this account.";
+    'adminUi.sessionIntro': "Review active sessions. Revoking a session signs that device out.";
+    'adminUi.auditIntro': "Review recorded security events. Use filters to narrow the time range or account.";
+    'adminUi.rolesIntro': "Review the permissions each role grants. Assign reviewed roles to an account below.";
+    'adminUi.methodIntro': "Review sign-in methods before changing account access.";
+    'adminUi.auditExport': "Export audit events";
+    'adminUi.sessionFilters': "Filter sessions";
+    'adminUi.auditFilters': "Filter audit events";
+    'adminUi.expires': "Expires";
+    'adminUi.device': "Device";
+    'adminUi.permissions': "Permissions";
+    'adminUi.accountActions': "Account actions";
+    'adminUi.revokeExplanation': "The user can sign in again unless their account is locked.";
+    'adminUi.resetFilters': "Reset filters";
+    'adminUi.advancedFilters': "Advanced filters";
+    'adminUi.exportAccounts': "Export accounts";
+    'adminUi.noAccounts': "No matching accounts. Try changing your filters.";
+    'adminUi.returnOverview': "Return to overview";
+    'adminUi.returnUsers': "Back to users";
+    'adminUi.reviewCase': "Review case";
+    'adminUi.createCase': "Create a support case";
+    'adminUi.noteHelp': "Notes are recorded in the audit trail. Do not include credentials or recovery secrets.";
+    'adminUi.healthIntro': "Reported observations from this host and its configured integrations.";
+    'adminUi.confirmFresh': "Sensitive actions require a recent sign-in and a reason.";
+    'adminUi.actor': "Actor account ID";
+    'adminUi.subject': "Subject account ID";
+    'adminUi.action': "Event action";
+    'adminUi.from': "From UTC (YYYY-MM-DDTHH:mmZ)";
+    'adminUi.to': "To UTC (YYYY-MM-DDTHH:mmZ)";
+    'adminUi.noticeSender': "Notification sender reported a failure.";
+    'adminUi.noticeProvider': "A provider credential is approaching expiry.";
+    'adminUi.noticePresentation': "The configured presentation needs an update.";
+    'adminUi.noticeTranslation': "Some translations are incomplete.";
+}>;
+/**
+ * Existing auth presentations still work; this factory also makes admin-owned copy translatable.
+ * `base` composes an existing presentation (the kit's, which carries the auth catalogue and the
+ * project's copy) with the admin catalogue instead of building the auth presentation here.
+ */
+export declare function createAdminPresentation(options?: Omit<PresentationOptions, 'defaults'> & {
+    base?: Presentation | undefined;
+}): Presentation;

package/dist/admin-copy.js

@@ -0,0 +1,71 @@
+import { createPresentation } from '@jimhoyd/urlcode-ui';
+import { createPresentation as createAuthPresentation } from '@jimhoyd/urlcode-auth';
+/** Console copy belongs to admin. Shared UI contains no account or operator workflows. */
+export const adminCatalogue = Object.freeze({
+    'adminUi.activityPeriod': 'Last 30 days',
+    'adminUi.activityDetails': 'View activity totals',
+    'adminUi.searchAccounts': 'Search accounts',
+    'adminUi.searchPlaceholder': 'Email, name or account ID',
+    'adminUi.createAccount': 'Create account',
+    'adminUi.sendSetup': 'Send setup link',
+    'adminUi.exportPage': 'Export page (CSV)',
+    'adminUi.exportAll': 'Export all (CSV)',
+    'adminUi.chartDescription': 'Thirty UTC days of sign-ups, sign-ins and failed sign-ins. Failed sign-ins use a dashed line. Exact values follow in the daily table.',
+    'adminUi.noSessions': 'No active sessions match these filters.',
+    'adminUi.noAudit': 'No audit events match these filters.',
+    'adminUi.noCases': 'No support cases to review.',
+    'adminUi.noRegistrations': 'No registration requests are waiting for approval.',
+    'adminUi.noNotes': 'No administrator notes yet.',
+    'adminUi.noActivity': 'No account activity recorded.',
+    'adminUi.noAlerts': 'No alerts reported.',
+    'adminUi.noMethods': 'No passkeys or external sign-in methods recorded.',
+    'adminUi.noRecovery': 'No manual recovery cases to review.',
+    'adminUi.noGrants': 'No additional permissions',
+    'adminUi.noTerms': 'No consent record is stored for this account.',
+    'adminUi.sessionIntro': 'Review active sessions. Revoking a session signs that device out.',
+    'adminUi.auditIntro': 'Review recorded security events. Use filters to narrow the time range or account.',
+    'adminUi.rolesIntro': 'Review the permissions each role grants. Assign reviewed roles to an account below.',
+    'adminUi.methodIntro': 'Review sign-in methods before changing account access.',
+    'adminUi.auditExport': 'Export audit events',
+    'adminUi.sessionFilters': 'Filter sessions',
+    'adminUi.auditFilters': 'Filter audit events',
+    'adminUi.expires': 'Expires',
+    'adminUi.device': 'Device',
+    'adminUi.permissions': 'Permissions',
+    'adminUi.accountActions': 'Account actions',
+    'adminUi.revokeExplanation': 'The user can sign in again unless their account is locked.',
+    'adminUi.resetFilters': 'Reset filters',
+    'adminUi.advancedFilters': 'Advanced filters',
+    'adminUi.exportAccounts': 'Export accounts',
+    'adminUi.noAccounts': 'No matching accounts. Try changing your filters.',
+    'adminUi.returnOverview': 'Return to overview',
+    'adminUi.returnUsers': 'Back to users',
+    'adminUi.reviewCase': 'Review case',
+    'adminUi.createCase': 'Create a support case',
+    'adminUi.noteHelp': 'Notes are recorded in the audit trail. Do not include credentials or recovery secrets.',
+    'adminUi.healthIntro': 'Reported observations from this host and its configured integrations.',
+    'adminUi.confirmFresh': 'Sensitive actions require a recent sign-in and a reason.',
+    'adminUi.actor': 'Actor account ID',
+    'adminUi.subject': 'Subject account ID',
+    'adminUi.action': 'Event action',
+    'adminUi.from': 'From UTC (YYYY-MM-DDTHH:mmZ)',
+    'adminUi.to': 'To UTC (YYYY-MM-DDTHH:mmZ)',
+    'adminUi.noticeSender': 'Notification sender reported a failure.',
+    'adminUi.noticeProvider': 'A provider credential is approaching expiry.',
+    'adminUi.noticePresentation': 'The configured presentation needs an update.',
+    'adminUi.noticeTranslation': 'Some translations are incomplete.',
+});
+/**
+ * Existing auth presentations still work; this factory also makes admin-owned copy translatable.
+ * `base` composes an existing presentation (the kit's, which carries the auth catalogue and the
+ * project's copy) with the admin catalogue instead of building the auth presentation here.
+ */
+export function createAdminPresentation(options = {}) {
+    const entries = Object.entries(options.catalogues ?? {});
+    const isAdmin = (key) => Object.hasOwn(adminCatalogue, key);
+    const { base: given, ...rest } = options;
+    const base = given ?? createAuthPresentation({ ...rest, catalogues: Object.fromEntries(entries.map(([locale, catalogue]) => [locale, Object.fromEntries(Object.entries(catalogue).filter(([key]) => !isAdmin(key)))])) });
+    const own = createPresentation({ ...rest, defaults: adminCatalogue, catalogues: Object.fromEntries(entries.map(([locale, catalogue]) => [locale, Object.fromEntries(Object.entries(catalogue).filter(([key]) => isAdmin(key)))])) });
+    const sources = new Map(Object.entries(adminCatalogue).map(([key, value]) => [value, key]));
+    return Object.freeze({ ...base, english: Object.freeze({ ...base.english, ...adminCatalogue }), coverage(locale) { const auth = base.coverage(locale), admin = own.coverage(locale); return { missing: [...auth.missing, ...admin.missing.filter(isAdmin)], mismatched: [...auth.mismatched, ...admin.mismatched.filter(isAdmin)] }; }, resolve(preferences) { const context = base.resolve(preferences), copy = own.resolve(preferences); return Object.freeze({ ...context, has(key) { return isAdmin(key) ? copy.has(key) : context.has(key); }, textSource(source) { const key = sources.get(source); return key ? copy.text(key) : context.textSource(source); }, text(key, values) { return isAdmin(key) ? copy.text(key, values) : context.text(key, values); } }); } });
+}

package/dist/admin-dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { AuthService, AuthPrincipal, PresentationContext } from '@jimhoyd/urlcode-auth';
+export declare function dashboardSummary(stats: Awaited<ReturnType<AuthService['dashboard']>>, mount: string, principal: AuthPrincipal, presentation: PresentationContext): string;

package/dist/admin-dashboard.js

@@ -0,0 +1,14 @@
+import { escapeHtml } from '@jimhoyd/urlcode-ui';
+import { hasPermission } from '@jimhoyd/urlcode-auth';
+export function dashboardSummary(stats, mount, principal, presentation) {
+    const text = (value) => escapeHtml(presentation.textSource(value));
+    const number = (value) => escapeHtml(presentation.text('number.value', { value }));
+    const items = [['Accounts', stats.users, '/users', 'auth.users.read'], ['Active accounts', stats.users - stats.locked - stats.pendingDeletion, '/users?status=active', 'auth.users.read'], ['Locked accounts', stats.locked, '/users?status=locked', 'auth.users.read'], ['Pending deletion', stats.pendingDeletion, '/users?status=pending-delete', 'auth.users.read'], ['Sessions', stats.sessions, '/sessions', 'auth.sessions.manage'], ['Waiting for approval', stats.waitlist, '/registrations', 'auth.users.manage']];
+    const totals = `<div class="ui-metrics" role="group" aria-label="${escapeHtml(presentation.text('message.adminTotals', { users: stats.users, locked: stats.locked, pending: stats.pendingDeletion, sessions: stats.sessions, waitlist: stats.waitlist }))}">${items.filter(([, , , permission]) => hasPermission(principal, permission)).map(([label, count, path]) => `<a class="ui-card ui-metric" href="${escapeHtml(mount + path)}"><span class="ui-muted">${text(label)}</span><strong>${number(count)}</strong><span aria-hidden="true">↗</span></a>`).join('')}</div>`;
+    const days = stats.daily.slice(-30), peak = Math.max(1, ...days.flatMap(day => [day.signUps, day.signIns, day.failedSignIns]));
+    const colors = ['var(--chart-1)', 'var(--chart-2)', 'var(--chart-3)'];
+    const lines = ['signUps', 'signIns', 'failedSignIns'].map((key, index) => `<polyline fill="none" stroke="${colors[index]}" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"${index === 2 ? ' stroke-dasharray="5 4"' : ''} points="${days.map((day, i) => `${64 + i * 526 / Math.max(1, days.length - 1)},${160 - Math.round(Math.max(0, day[key]) / peak * 130)}`).join(' ')}"/>`).join('');
+    const grid = [30, 95, 160].map(y => `<line x1="64" y1="${y}" x2="590" y2="${y}" stroke="currentColor" opacity="0.1"/>`).join('');
+    const labels = `<text x="54" y="34" text-anchor="end" font-size="14" fill="currentColor">${number(peak)}</text><text x="54" y="164" text-anchor="end" font-size="14" fill="currentColor">${number(0)}</text>${days.length ? `<text x="64" y="184" font-size="14" fill="currentColor">${escapeHtml(days[0].day)} UTC</text><text x="590" y="184" text-anchor="end" font-size="14" fill="currentColor">${escapeHtml(days.at(-1).day)} UTC</text>` : ''}`;
+    return totals + `<section class="ui-card ui-chart" aria-labelledby="activity-heading"><div class="ui-section-heading"><div><h2 id="activity-heading">${text('Authentication activity')}</h2><p class="ui-muted">${escapeHtml(presentation.textSource('Last 30 days'))}</p></div><span class="ui-badge">UTC</span></div><svg viewBox="0 0 620 190" role="img" aria-labelledby="auth-chart-title auth-chart-description"><title id="auth-chart-title">${text('Authentication activity')}</title><desc id="auth-chart-description">${text('Thirty UTC days of sign-ups, sign-ins and failed sign-ins. Failed sign-ins use a dashed line. Exact values follow in the daily table.')}</desc>${grid}${lines}${labels}</svg><div class="ui-chart-legend"><span><i class="ui-chart-key ui-chart-key-blue" aria-hidden="true"></i>${escapeHtml(presentation.text('copy.signUps'))}</span><span><i class="ui-chart-key ui-chart-key-green" aria-hidden="true"></i>${escapeHtml(presentation.text('copy.signIns'))}</span><span><i class="ui-chart-key ui-chart-key-red" aria-hidden="true"></i>${escapeHtml(presentation.text('copy.failedSignIns'))}</span></div></section>`;
+}

package/dist/admin-detail.d.ts

@@ -0,0 +1,14 @@
+import type { AuthService, AuthUser, AuthPrincipal, PresentationContext } from '@jimhoyd/urlcode-auth';
+import type { Screen } from './admin-ui.ts';
+export declare function accountDetail(input: {
+    user: AuthUser;
+    principal: AuthPrincipal;
+    mount: string;
+    csrf: string;
+    presentation: PresentationContext;
+    sessions?: Awaited<ReturnType<AuthService['listSessions']>>;
+    activity?: Awaited<ReturnType<AuthService['listAudit']>>;
+    notes?: Awaited<ReturnType<AuthService['listAudit']>>;
+    operations: boolean;
+    recovery?: boolean;
+}): Screen;

package/dist/admin-detail.js

@@ -0,0 +1,27 @@
+import { escapeHtml, icon, emptyState, hiddenField, postForm } from '@jimhoyd/urlcode-ui';
+import { formField, hasPermission } from '@jimhoyd/urlcode-auth';
+import { adminTime } from "./admin-screens.js";
+import { markup } from "./admin-ui.js";
+export function accountDetail(input) {
+    const { user, principal, mount, csrf, presentation, sessions, activity, notes } = input;
+    const plain = (source) => presentation.textSource(source), text = (source) => escapeHtml(plain(source)), value = escapeHtml;
+    const url = (path) => escapeHtml(mount + path), id = encodeURIComponent(user.id), field = (name, label) => formField(name, plain(label));
+    const form = (path, fields, label, destructive = false) => postForm({ action: mount + path, csrf, fields: hiddenField('accountId', user.id) + fields, label: plain(label), destructive, className: 'ui-form-grid' });
+    const sections = [['overview', 'Overview'], ['methods', 'Sign-in methods'], ['sessions', 'Sessions'], ['recovery', 'Recovery'], ['activity', 'Activity'], ['data', 'Data']];
+    const empty = (message) => emptyState(plain(message));
+    const facts = [['Account ID', user.id], ['Email', user.email], ['Status', user.status], ['Email verified', user.emailVerified ? 'Yes' : 'No'], ['Roles', user.roles.join(', ')], ['Created', new Date(user.created).toISOString()], ['Display name', user.profile?.displayName ?? '—'], ['Language', user.profile?.locale ?? '—']];
+    const operations = input.operations && user.id !== principal.id ? `<a class="ui-button-secondary" href="${url('/account-operations?accountId=' + id)}">${text('Account administration')}</a>` : '';
+    const overview = `<dl class="ui-definition-grid">${facts.map(([name, content]) => `<dt>${text(name)}</dt><dd>${value(content)}</dd>`).join('')}</dl>` + (hasPermission(principal, 'auth.users.reveal') ? `<details><summary>${text('Reveal email address')}</summary>${form('/users/reveal', field('reason', 'Reason'), 'Reveal email address')}</details>` : '') + (notes ? `<h3>${text('Administrator notes')}</h3>${notes.events.length ? `<ul class="ui-list">${notes.events.map(note => `<li><p>${value(note.reason)}</p><small class="ui-muted">${value(note.actor)} · ${adminTime(note.created)}</small></li>`).join('')}</ul>` : empty('No administrator notes yet.')}` : '') + (hasPermission(principal, 'auth.users.manage') ? `<details><summary>${text('Save administrator note')}</summary><p class="ui-muted">${text('Notes are recorded in the audit trail. Do not include credentials or recovery secrets.')}</p>${form('/users/note', field('reason', 'Administrator note'), 'Save administrator note')}</details>` : '');
+    const sessionBody = sessions ? (sessions.length ? `<ul class="ui-list">${sessions.map(session => `<li><strong>${value(session.deviceLabel ?? plain('Unknown device'))}</strong><dl class="ui-definition-grid"><dt>${text('Created')}</dt><dd>${adminTime(session.created)}</dd><dt>${text('Expires')}</dt><dd>${adminTime(session.expires)}</dd></dl><details><summary>${text('Revoke this session')}</summary>${form('/sessions/revoke-one', hiddenField('sessionId', session.id) + field('reason', 'Reason'), 'Revoke this session', true)}</details></li>`).join('')}</ul><details class="ui-danger-zone"><summary>${text('Revoke all sessions')}</summary><p class="ui-muted">${text('The user can sign in again unless their account is locked.')}</p>${form('/sessions/revoke', field('reason', 'Reason'), 'Revoke all sessions', true)}</details>` : empty('No active sessions match these filters.')) : empty('Session management permission is required.');
+    const activityBody = activity ? (activity.events.length ? `<ul class="ui-list">${activity.events.map(event => `<li><code>${value(event.action)}</code><p class="ui-muted">${adminTime(event.created)} · ${value(event.actor)}</p></li>`).join('')}</ul>` : empty('No account activity recorded.')) + `<a class="ui-button-secondary" href="${url('/audit?subject=' + id)}">${text('View account audit')}</a>` : empty('Audit permission is required.');
+    const recoveryLinks = hasPermission(principal, 'auth.cases.read') ? `<div class="ui-actions">${input.recovery ? `<a class="ui-button-secondary" href="${url('/recovery-cases')}">${text('Manual account recovery')}</a>` : ''}<a class="ui-button-secondary" href="${url('/cases')}">${text('Security cases')}</a></div>` : '';
+    const bodies = {
+        overview,
+        methods: `<dl class="ui-definition-grid"><dt>${text('Authenticator enabled')}</dt><dd>${text(user.totpEnabled ? 'Yes' : 'No')}</dd><dt>${text('Passkey second factor enabled')}</dt><dd>${text(user.passkeyMfaEnabled ? 'Yes' : 'No')}</dd></dl>` + operations,
+        sessions: sessionBody,
+        recovery: `<p class="ui-muted">${text('Recovery contacts are not supported in this release. Manual evidence requires independent operator assessment.')}</p>` + recoveryLinks,
+        activity: activityBody,
+        data: `<h3>${text('Consent record')}</h3>${user.profile?.terms ? `<pre>${value(JSON.stringify(user.profile.terms, null, 2))}</pre>` : empty('No consent record is stored for this account.')}` + (hasPermission(principal, 'auth.users.export') ? `<details><summary>${icon('download')}<span>${text('Export account data')}</span></summary>${form('/users/export', field('reason', 'Reason'), 'Export account data')}</details>` : '') + operations,
+    };
+    return { name: 'admin/user-detail', view: { backHref: mount + '/users', backIcon: markup(icon('arrow-left')), backLabel: plain('Back to users'), status: user.status, sectionsLabel: plain('Account sections'), sections: sections.map(([key, label]) => ({ href: '#detail-' + key, label: plain(label) })), panels: sections.map(([key, label]) => ({ id: key, heading: plain(label), content: markup(bodies[key]) })) } };
+}

package/dist/admin-health.d.ts

@@ -0,0 +1,24 @@
+/** Operator-supplied observations only. This adapter never fetches project URLs or exposes provider errors. */
+export type HealthStatus = 'healthy' | 'degraded' | 'unavailable' | 'unknown';
+export interface AdminHealthSnapshot {
+    checkedAt: string;
+    runtime: {
+        status: HealthStatus;
+        readiness: HealthStatus;
+        version: string;
+        routes: number;
+    };
+    sender: HealthStatus;
+    providers: readonly {
+        id: string;
+        status: HealthStatus;
+    }[];
+    alerts: readonly ('sender-failed' | 'provider-expiring' | 'presentation-outdated' | 'translation-incomplete')[];
+}
+export type AdminHealthProvider = (context: {
+    signal: AbortSignal;
+}) => Promise<AdminHealthSnapshot>;
+/** Validate and copy only the allowed fields: arbitrary errors, URLs, credentials and metadata never cross this boundary. */
+export declare function validateHealthSnapshot(value: AdminHealthSnapshot): AdminHealthSnapshot;
+/** Bound concurrent operator callbacks even when an adapter ignores cancellation. */
+export declare function createHealthReader(provider: AdminHealthProvider): () => Promise<AdminHealthSnapshot | null>;

package/dist/admin-health.js

@@ -0,0 +1,33 @@
+import { withDeadline } from '@jimhoyd/urlcode-ui';
+const statuses = new Set(['healthy', 'degraded', 'unavailable', 'unknown']);
+const alerts = new Set(['sender-failed', 'provider-expiring', 'presentation-outdated', 'translation-incomplete']);
+/** Validate and copy only the allowed fields: arbitrary errors, URLs, credentials and metadata never cross this boundary. */
+export function validateHealthSnapshot(value) {
+    if (!value || typeof value.checkedAt !== 'string' || !Number.isFinite(Date.parse(value.checkedAt)) || new Date(value.checkedAt).toISOString() !== value.checkedAt || !value.runtime || !statuses.has(value.runtime.status) || !statuses.has(value.runtime.readiness) || typeof value.runtime.version !== 'string' || !/^[A-Za-z0-9.+_-]{1,64}$/.test(value.runtime.version) || !Number.isSafeInteger(value.runtime.routes) || value.runtime.routes < 0 || value.runtime.routes > 1000000 || !statuses.has(value.sender) || !Array.isArray(value.providers) || value.providers.length > 20 || !Array.isArray(value.alerts) || value.alerts.length > 20)
+        throw new Error('Invalid health snapshot');
+    const ids = new Set();
+    const providers = value.providers.map(provider => {
+        if (!provider || typeof provider.id !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(provider.id) || ids.has(provider.id) || !statuses.has(provider.status))
+            throw new Error('Invalid provider health');
+        ids.add(provider.id);
+        return { id: provider.id, status: provider.status };
+    });
+    if (value.alerts.some(alert => !alerts.has(alert)))
+        throw new Error('Invalid health alert');
+    return { checkedAt: value.checkedAt, runtime: { status: value.runtime.status, readiness: value.runtime.readiness, version: value.runtime.version, routes: value.runtime.routes }, sender: value.sender, providers, alerts: [...new Set(value.alerts)] };
+}
+/** Bound concurrent operator callbacks even when an adapter ignores cancellation. */
+export function createHealthReader(provider) {
+    let active = false;
+    return async () => {
+        if (active)
+            return null;
+        active = true;
+        try {
+            return await withDeadline(signal => Promise.resolve().then(() => provider({ signal })).then(validateHealthSnapshot).finally(() => { active = false; }), 2000, 'Health observation timed out');
+        }
+        catch {
+            return null;
+        }
+    };
+}

package/dist/admin-presentation.d.ts

@@ -0,0 +1,3 @@
+import { pageResponse } from '@jimhoyd/urlcode-auth';
+/** Trusted admin composition only; the reusable UI package has no knowledge of this shell. */
+export declare function adminPage(...args: Parameters<typeof pageResponse>): ReturnType<typeof pageResponse>;

package/dist/admin-presentation.js

@@ -0,0 +1,20 @@
+import { escapeHtml } from '@jimhoyd/urlcode-ui';
+import { pageResponse } from '@jimhoyd/urlcode-auth';
+/** The console shell for the primitive path only; the kit renders its own from `layout: 'application'`. */
+function primitiveShell(title, sidebar, content, presentation) {
+    const label = escapeHtml(presentation?.textSource(title) ?? title);
+    return `<div class="ui-shell">${sidebar}<div class="ui-content" id="admin-content" tabindex="-1"><header class="ui-page-header"><h1>${label}</h1></header>${content}</div></div>`;
+}
+/** Trusted admin composition only; the reusable UI package has no knowledge of this shell. */
+export function adminPage(...args) {
+    const [title, content, status, headers, script, presentation] = args;
+    const boundary = content.startsWith('<aside class="ui-sidebar"') ? content.indexOf('</aside>') + 8 : 0;
+    if (boundary < 8)
+        return pageResponse(...args);
+    const body = primitiveShell(title, content.slice(0, boundary), content.slice(boundary), presentation);
+    const response = pageResponse(title, body, status, headers, script, presentation, args[6], 'application');
+    // Only trusted document structure is adjusted. Preserve CSP nonces, theme scripts and headers verbatim.
+    let html = new TextDecoder().decode(response.body);
+    html = html.replace('href="#main"', 'href="#admin-content"').replace(/<h1>[^]*?<\/h1>/, '');
+    return { ...response, body: new TextEncoder().encode(html) };
+}

package/dist/admin-recovery.d.ts

@@ -0,0 +1,24 @@
+import type { ScreenOptions } from './admin-ui.ts';
+import type { ExtensionRequest, ExtensionInstance } from '@jimhoyd/urlcode/extensions';
+import { AuthHttp } from '@jimhoyd/urlcode-auth';
+import type { AuthPrincipal, ManualRecoveryService, ManualRecoveryDelivery } from '@jimhoyd/urlcode-auth';
+export interface AdminRecoveryOptions {
+    service: ManualRecoveryService & {
+        closeCase(input: {
+            actorToken: string;
+            caseId: string;
+            reason: string;
+        }): Promise<unknown>;
+        addCaseNote(input: {
+            actorToken: string;
+            caseId: string;
+            note: string;
+        }): Promise<unknown>;
+    };
+    sendRecovery?: (message: ManualRecoveryDelivery) => Promise<void>;
+}
+/** The service is the authorization boundary; this handler supplies CSRF and delivery gates. */
+export declare function createAdminRecovery(options: AdminRecoveryOptions, http: AuthHttp, mount: string): {
+    enabled: () => any;
+    handle(request: ExtensionRequest, principal: AuthPrincipal, actorToken: string, render: ScreenOptions): Promise<Awaited<ReturnType<ExtensionInstance["handle"]>> | undefined>;
+};