@jimhoyd/urlcode-admin 0.1.0-alpha.1

package/dist/admin-ui.js

@@ -0,0 +1,71 @@
+/**
+ * Renders one admin screen either through the urlcode-ui kit (when the host
+ * supplied the `ui` extension and the runtime activated it) or through the
+ * shared primitives inside the console shell. Both paths render the same
+ * `admin/*` template with the same view; only the layout around it differs.
+ * Flows, permissions, freshness gates, escaping, CSRF and headers stay in the
+ * extension code that computes the view.
+ */
+import { compileTemplate, Markup } from '@jimhoyd/urlcode-ui';
+import { AuthHttpError, httpFailure, wantsJson } from '@jimhoyd/urlcode-auth';
+import { adminPage } from "./admin-presentation.js";
+import { adminTemplates } from "./admin-templates.js";
+import { createAdminPresentation } from "./admin-copy.js";
+/** Test hook: sees every screen before it renders, with the path that renders it. */
+export const screenObserver = {};
+const localTemplates = new Map();
+function localTemplate(name) {
+    let template = localTemplates.get(name);
+    if (!template && Object.hasOwn(adminTemplates, name)) {
+        template = compileTemplate(name, adminTemplates[name].source);
+        localTemplates.set(name, template);
+    }
+    return template;
+}
+/** The kit a request renders through, or nothing when the host gave no `ui` or the runtime has not activated it. */
+export const activeKit = (ui) => ui?.active ? ui.kit : undefined;
+const composed = new WeakMap();
+/**
+ * The copy source: the host's presentation; else the kit's, composed with the admin catalogue, when the host registered
+ * the auth catalogue with the ui extension (the kit's own catalogue limit leaves no room for the admin catalogue too);
+ * else the bundled English.
+ */
+export function presentationSource(presentation, ui, fallback) {
+    if (presentation)
+        return presentation;
+    const kit = activeKit(ui);
+    if (!kit || !Object.hasOwn(kit.presentation.english, 'page.admin'))
+        return fallback;
+    let source = composed.get(kit.presentation);
+    if (!source) {
+        source = createAdminPresentation({ base: kit.presentation });
+        composed.set(kit.presentation, source);
+    }
+    return source;
+}
+/** Renders a screen: through `ui.kit` when the host supplied the ui extension and it is active, otherwise through the shared primitives. */
+export function screenResponse(title, screen, options) {
+    if (!Object.hasOwn(adminTemplates, screen.name))
+        throw new Error(`Unknown admin screen: ${screen.name.slice(0, 64)}`);
+    const kit = activeKit(options.ui);
+    screenObserver.current?.(screen, kit ? 'kit' : 'primitives');
+    if (!kit) {
+        const markup = localTemplate(screen.name).render(screen.view, options.presentation, localTemplate).html;
+        return adminPage(title, (options.shell?.sidebar ?? '') + markup, options.status ?? 200, options.headers ?? [], undefined, options.presentation);
+    }
+    const context = kit.resolveContext(options.preferences);
+    const rendered = kit.render(screen.name, screen.view, options.presentation);
+    // The kit owns the console shell on this path: it builds the sidebar, the page header and the skip target from `nav`, `menu` and the title.
+    const page = kit.wrap(rendered, { title: options.presentation.textSource(title), context, layout: options.shell ? 'application' : 'default', ...(options.status !== undefined ? { status: options.status } : {}), ...(options.headers ? { headers: options.headers } : {}), ...(options.shell ? { nav: options.shell.nav, menu: options.shell.menu } : {}) });
+    return page;
+}
+/** The failure page: JSON for API clients, otherwise the `admin/status` screen with the same status and message auth's `httpFailure` derives. */
+export function failureResponse(error, request, options) {
+    if (wantsJson(request) || !activeKit(options.ui))
+        return httpFailure(error, request, options.presentation);
+    const known = error instanceof AuthHttpError || (error instanceof Error && 'status' in error && typeof error.status === 'number' && error.status >= 400 && error.status < 500);
+    const status = known ? error.status : 500;
+    const source = error instanceof AuthHttpError ? error.message : status >= 500 ? 'Service unavailable' : 'Request could not be completed';
+    return screenResponse('Request could not be completed', { name: 'admin/status', view: { alert: true, message: options.presentation.textSource(source), href: null, label: null } }, { ...options, status });
+}
+export const markup = (html) => new Markup(html);

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

@@ -0,0 +1,3 @@
+import type { AuthService } from '@jimhoyd/urlcode-auth';
+/** Buffer the complete bounded selection; failures never return partial CSV. */
+export declare function exportUserRange(service: AuthService, actorToken: string, query: URLSearchParams, reason: string): Promise<Uint8Array>;

package/dist/admin-user-export.js

@@ -0,0 +1,57 @@
+import { AuthHttpError, hasPermission } from '@jimhoyd/urlcode-auth';
+import { userFilters, usersCsv } from "./admin-reporting.js";
+/** Buffer the complete bounded selection; failures never return partial CSV. */
+export async function exportUserRange(service, actorToken, query, reason) {
+    if (query.has('after'))
+        throw new AuthHttpError(400, 'Complete exports start at the beginning of the selection');
+    if (typeof reason !== 'string' || !reason.trim() || reason.length > 1000)
+        throw new AuthHttpError(400, 'A bounded export reason is required');
+    const filters = userFilters(query), deadline = performance.now() + 5000;
+    const bounded = async (operation) => {
+        const remaining = deadline - performance.now();
+        if (remaining <= 0)
+            throw new AuthHttpError(413, 'Narrow the user filters');
+        let timer;
+        try {
+            return await Promise.race([operation(), new Promise((_, reject) => { timer = setTimeout(() => reject(new AuthHttpError(413, 'Narrow the user filters')), remaining); })]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const authorize = async () => {
+        const actor = await bounded(() => service.authenticate(actorToken));
+        if (!actor || actor.impersonatorId || !hasPermission(actor, 'auth.users.read') || !hasPermission(actor, 'auth.users.export') || actor.authenticatedAt <= 0 || Date.now() - actor.authenticatedAt > 300000)
+            throw new AuthHttpError(403, 'Fresh user export authority required');
+    };
+    const chunks = [usersCsv([])], seen = new Set(), cursors = new Set();
+    let bytes = chunks[0].byteLength, after;
+    do {
+        await authorize();
+        const page = await bounded(() => service.listUsers({ ...filters, limit: 100, ...(after ? { after } : {}) }));
+        if (seen.size + page.users.length > 5000)
+            throw new AuthHttpError(413, 'Narrow the user filters');
+        for (const user of page.users) {
+            if (seen.has(user.id))
+                throw new AuthHttpError(409, 'Users changed during export; restart the selection');
+            seen.add(user.id);
+            const exported = await bounded(() => service.adminExport({ actorToken, accountId: user.id, reason }));
+            const full = usersCsv([{ ...exported.user, ...('observedLastSeen' in user ? { observedLastSeen: user.observedLastSeen } : {}) }]);
+            const row = full.slice(chunks[0].byteLength);
+            bytes += row.byteLength;
+            if (bytes > 4 * 1024 * 1024)
+                throw new AuthHttpError(413, 'Narrow the user filters');
+            chunks.push(row);
+        }
+        after = page.next;
+        if (after) {
+            if (cursors.has(after))
+                throw new AuthHttpError(409, 'Users changed during export; restart the selection');
+            cursors.add(after);
+        }
+    } while (after);
+    await authorize();
+    if (performance.now() > deadline)
+        throw new AuthHttpError(413, 'Narrow the user filters');
+    return Buffer.concat(chunks, bytes);
+}

package/dist/admin-users.d.ts

@@ -0,0 +1,13 @@
+import type { AuthPrincipal, AuthUser, PresentationContext } from '@jimhoyd/urlcode-auth';
+import type { Screen } from './admin-ui.ts';
+/** Account workflows and authority stay here; URLCode UI supplies only generic visual primitives. */
+export declare function userDirectory(input: {
+    users: AuthUser[];
+    next?: string;
+    query: URLSearchParams;
+    principal: AuthPrincipal;
+    mount: string;
+    csrf: string;
+    presentation: PresentationContext;
+    canSendSetup: boolean;
+}): Screen;

package/dist/admin-users.js

@@ -0,0 +1,19 @@
+import { escapeHtml, icon, hiddenField, postForm } from '@jimhoyd/urlcode-ui';
+import { csrfField, formField, hasPermission } from '@jimhoyd/urlcode-auth';
+import { nextPage, observedLastSeen, userFilterFields, userFilterKeys } from "./admin-reporting.js";
+import { markup } from "./admin-ui.js";
+/** Account workflows and authority stay here; URLCode UI supplies only generic visual primitives. */
+export function userDirectory(input) {
+    const { users, query, principal, mount, csrf, presentation } = input;
+    const text = (source) => presentation.textSource(source), html = (source) => escapeHtml(text(source));
+    const tr = (key, values) => presentation.text(key, values), trh = (key, values) => escapeHtml(tr(key, values));
+    const field = (name, label, type = 'text') => formField(name, text(label), type);
+    const form = (path, fields, label, destructive = false) => postForm({ action: mount + path, csrf, fields, label: text(label), destructive, className: 'ui-form-grid' });
+    const manage = hasPermission(principal, 'auth.users.manage'), sessions = hasPermission(principal, 'auth.sessions.manage'), select = manage || sessions;
+    const setup = input.canSendSetup && hasPermission(principal, 'auth.users.create') ? { summary: text('Create account'), form: markup(form('/users/create', field('email', 'Email address', 'email') + field('reason', 'Reason'), 'Send setup link')) } : null;
+    const filters = `<form method="get" action="${escapeHtml(mount + '/users')}">${userFilterFields(query, text)}<div class="ui-toolbar"><button type="submit">${icon('search')}<span>${trh('users.filter.apply')}</span></button><a href="${escapeHtml(mount + '/users' + (query.get('lang') ? '?lang=' + encodeURIComponent(query.get('lang')) : ''))}">${html('Reset filters')}</a></div></form>`;
+    const exports = hasPermission(principal, 'auth.users.export') ? { summary: markup(icon('download') + `<span>${html('Export accounts')}</span>`), forms: markup(form('/users/export-page', [...userFilterKeys, 'after'].map(key => hiddenField(key, query.get(key) || '')).join('') + field('reason', 'Reason') + `<p class="ui-muted">${trh('copy.exportThisFilteredPageOnlyAtMost50AccountsEmailAddressesStayMasked')}</p>`, 'Export page (CSV)') + form('/users/export-range', userFilterKeys.map(key => hiddenField(key, query.get(key) || '')).join('') + field('reason', 'Reason') + `<p class="ui-muted">${html('Complete export: at most 5,000 accounts, 4 MiB and 5 seconds. Narrow filters if the limit is exceeded.')}</p>`, 'Export all (CSV)')) } : null;
+    const bulk = select ? { summary: tr('copy.bulkAction'), form: markup(`<form class="ui-form-grid" id="bulk-users" method="post" action="${escapeHtml(mount + '/users/bulk')}">${csrfField(csrf)}<label>${trh('copy.bulkAction')}<select name="action">${manage ? `<option value="lock">${trh('copy.lock')}</option><option value="unlock">${trh('copy.unlock')}</option>` : ''}${sessions ? `<option value="revoke-sessions">${trh('action.revokeSessions')}</option>` : ''}</select></label>${field('reason', 'Reason')}${field('confirmation', 'Type LOCK, UNLOCK or REVOKE-SESSIONS followed by a space and the selected count')}<p class="ui-muted">${trh('copy.selectAccountsInTheTableAllSelectedAccountsMustBePermittedOtherwiseNoneAreChanged')}</p><button class="ui-button-destructive" type="submit">${trh('copy.applyBulkAction')}</button></form>`) } : null;
+    const rows = users.map(user => `<tr><td>${user.id !== principal.id && user.status !== 'pending-delete' && select ? `<input type="checkbox" form="bulk-users" name="selected.${escapeHtml(user.id)}" value="yes" aria-label="${trh('action.selectAccount', { account: user.email })}">` : ''}</td><td><a href="${escapeHtml(mount + '/users/detail?id=' + encodeURIComponent(user.id))}"><strong>${escapeHtml(user.email)}</strong></a><small class="ui-muted ui-account-id">${escapeHtml(user.id)}</small></td><td><span class="ui-badge" data-status="${escapeHtml(user.status)}">${html(user.status)}</span></td><td class="ui-muted">${observedLastSeen(user) ? `<time datetime="${escapeHtml(observedLastSeen(user))}">${escapeHtml(observedLastSeen(user).replace('T', ' ').slice(0, 16) + ' UTC')}</time>` : '—'}</td><td>${user.roles.map(role => `<span class="ui-badge">${escapeHtml(role)}</span>`).join(' ')}</td><td>${manage && user.id !== principal.id && user.status !== 'pending-delete' ? `<details><summary>${html(user.status === 'active' ? 'Lock account' : 'Unlock account')}</summary>${form('/users/status', hiddenField('accountId', user.id) + hiddenField('status', user.status === 'active' ? 'locked' : 'active') + field('reason', 'Reason'), user.status === 'active' ? 'Lock account' : 'Unlock account', user.status === 'active')}</details>` : ''}</td></tr>`).join('');
+    return { name: 'admin/users', view: { setup, filters: markup(filters), heading: tr('nav.users'), count: tr('number.value', { value: users.length }), caption: tr('copy.accountsEmailAddressesMasked'), columns: { select: tr('copy.select'), account: tr('nav.account'), status: tr('copy.status'), lastSeen: tr('users.filter.lastSeen'), roles: tr('nav.roles'), actions: tr('copy.actions') }, rows: markup(rows), empty: text('No matching accounts. Try changing your filters.'), caveat: tr('users.filter.activityCaveat'), nextHref: input.next ? nextPage(mount + '/users', query, input.next, userFilterKeys) : null, nextLabel: tr('action.next'), bulk, exports } };
+}

package/dist/admin.d.ts

@@ -0,0 +1,37 @@
+import type { UiHost } from './admin-ui.ts';
+import type { AdminAccountDelivery } from '@jimhoyd/urlcode-auth';
+import type { ManualRecoveryDelivery } from '@jimhoyd/urlcode-auth';
+import type { AdminHealthProvider } from './admin-health.ts';
+import type { RuntimeExtension } from '@jimhoyd/urlcode/extensions';
+import type { AuthService, Presentation } from '@jimhoyd/urlcode-auth';
+export interface AdminExtensionOptions {
+    sendAccountAdministration?: (message: AdminAccountDelivery & {
+        signal: AbortSignal;
+    }) => Promise<void>;
+    sendRecovery?: (message: ManualRecoveryDelivery) => Promise<void>;
+    presentation?: Presentation;
+    /** The `ui` extension from `createUiExtension`, declared before admin in the host file. Screens then render through its kit. */
+    ui?: UiHost;
+    health?: AdminHealthProvider;
+    service: AuthService;
+    csrfKey: Uint8Array;
+    projectSha256: string;
+    authMount?: string;
+    notifyImpersonation?: (message: {
+        email: string;
+        actorId: string;
+        reason: string;
+        signal: AbortSignal;
+    }) => Promise<void>;
+    sendSetup?: (message: {
+        email: string;
+        token: string;
+        signal: AbortSignal;
+    }) => Promise<void>;
+    sendInvitation?: (message: {
+        email: string;
+        token: string;
+        signal: AbortSignal;
+    }) => Promise<void>;
+}
+export declare function adminExtension(options: AdminExtensionOptions): RuntimeExtension;

package/dist/admin.js

@@ -0,0 +1,304 @@
+import { rolesScreen, sessionsScreen, auditScreen, healthScreen, casesScreen, registrationsScreen } from "./admin-screens.js";
+import { createAdminPresentation } from "./admin-copy.js";
+import { userDirectory } from "./admin-users.js";
+import { escapeHtml, icon, postForm, withDeadline } from '@jimhoyd/urlcode-ui';
+import { failureResponse, markup, presentationSource, screenResponse } from "./admin-ui.js";
+import { dashboardSummary } from "./admin-dashboard.js";
+import { accountDetail } from "./admin-detail.js";
+import { exportUserRange } from "./admin-user-export.js";
+import { createAdminAccount } from "./admin-account.js";
+import { createAdminRecovery } from "./admin-recovery.js";
+import { exportAuditRange } from "./admin-audit-export.js";
+import { createHealthReader } from "./admin-health.js";
+import { maskEmail, sessionFilters, userFilters, userFilterKeys, auditFilters, selectedNames, selectedAccounts, usersCsv } from "./admin-reporting.js";
+import { AuthHttp, AuthHttpError, formField as baseField, jsonResponse, readFields, wantsJson, hasPermission } from '@jimhoyd/urlcode-auth';
+const defaultPresentation = createAdminPresentation();
+const schema = { type: 'object', additionalProperties: false, properties: {} };
+const permissions = ['auth.users.reveal', 'auth.audit.export', 'auth.health.read', 'auth.cases.read', 'auth.cases.manage', 'auth.users.impersonate', 'auth.users.export', 'auth.users.create', 'auth.users.read', 'auth.users.manage', 'auth.audit.read', 'auth.sessions.manage', 'auth.roles.read'];
+export function adminExtension(options) {
+    const authMount = options.authMount || '/account';
+    if (!/^\/[A-Za-z0-9/_-]*$/.test(authMount) || authMount.includes('//'))
+        throw new Error('Invalid auth mount');
+    return { name: 'admin', version: '1', projectSha256: options.projectSha256, targets: ['node'], schema, credentialHeaders: ['cookie', 'authorization', 'x-csrf-token'],
+        activate(_config, context) {
+            if (context.mounts.length !== 1)
+                throw new Error('Admin requires exactly one mount');
+            const readHealth = options.health ? createHealthReader(options.health) : undefined;
+            const mount = context.mounts[0], http = new AuthHttp({ origin: context.origin, csrfKey: options.csrfKey }), service = options.service;
+            const accounts = createAdminAccount({ service, ...(options.sendAccountAdministration ? { sendAccountAdministration: options.sendAccountAdministration } : {}) }, http, mount);
+            const recovery = createAdminRecovery({ service, ...(options.sendRecovery ? { sendRecovery: options.sendRecovery } : {}) }, http, mount);
+            function requirePermission(principal, permission) {
+                if (!hasPermission(principal, permission))
+                    throw new AuthHttpError(403, 'Permission required');
+            }
+            function navigation(principal, text, tr, current) {
+                const isCurrent = (path) => path === '/' ? (current === '/' || current === '/dashboard') : current === path || current.startsWith(path + '/');
+                const items = [{ href: mount + '/', label: tr('nav.overview'), current: isCurrent('/'), symbol: 'home' }, ...[['users', 'Users', 'auth.users.read', 'users'], ['sessions', 'Sessions', 'auth.sessions.manage', 'monitor'], ['registrations', 'Registration', 'auth.users.manage', 'mail'], ['roles', 'Roles', 'auth.roles.read', 'shield'], ['audit', 'Audit', 'auth.audit.read', 'list'], ['cases', 'Cases', 'auth.cases.read', 'circle-alert'], ['health', 'Service health', 'auth.health.read', 'activity']].filter(([_path, _label, permission]) => hasPermission(principal, permission)).map(([path, label, , symbol]) => ({ href: mount + '/' + path, label: text(label), current: isCurrent('/' + path), symbol })), ...(accounts.enabled() && hasPermission(principal, 'auth.users.manage') ? [{ href: mount + '/account-operations', label: tr('adminOps.title'), current: isCurrent('/account-operations'), symbol: 'settings' }] : []), ...(recovery.enabled() && hasPermission(principal, 'auth.cases.read') ? [{ href: mount + '/recovery-cases', label: tr('manualRecovery.title'), current: isCurrent('/recovery-cases'), symbol: 'key' }] : [])];
+                const link = (item) => `<a class="ui-nav-link" href="${escapeHtml(item.href)}"${item.current ? ' aria-current="page"' : ''}>${icon(item.symbol)}<span>${escapeHtml(item.label)}</span></a>`;
+                const menu = { label: tr('nav.account'), items: [{ href: authMount + '/account', label: tr('nav.account') }, { href: authMount + '/step-up', label: tr('action.confirm') }] };
+                const contents = `<nav aria-label="${escapeHtml(tr('page.admin'))}">${items.map(link).join('')}</nav><div class="ui-sidebar-footer"><a class="ui-nav-link" href="${escapeHtml(authMount + '/account')}">${icon('user')}<span>${escapeHtml(tr('nav.account'))}</span></a><a class="ui-nav-link" href="${escapeHtml(authMount + '/step-up')}">${icon('lock')}<span>${escapeHtml(tr('action.confirm'))}</span></a></div>`;
+                return { sidebar: `<aside class="ui-sidebar"><a class="ui-brand" href="${escapeHtml(mount)}"><span aria-hidden="true">U</span><strong>URLCode</strong></a><div class="ui-desktop-navigation"><p class="ui-muted">${escapeHtml(tr('page.admin'))}</p>${contents}</div><details class="ui-mobile-navigation"><summary>${icon('list')}<span>${escapeHtml(tr('page.admin'))}</span></summary>${contents}</details></aside>`, nav: items.map(({ href, label, current }) => ({ href, label, current })), menu };
+            }
+            return { async handle(request) {
+                    // The runtime activates `ui` before admin, but its kit is read per request, never captured at activation.
+                    const source = presentationSource(options.presentation, options.ui, defaultPresentation);
+                    let preferences = { ...(request.query.get('lang') ? { queryLocale: request.query.get('lang') } : {}), ...(request.headers.get('accept-language') ? { acceptLanguage: request.headers.get('accept-language') } : {}) };
+                    let presentation = source.resolve(preferences);
+                    const render = () => ({ presentation, preferences, ui: options.ui });
+                    const tr = (key, values) => presentation.text(key, values);
+                    const formField = (name, label, type = 'text', autocomplete = 'off', required = true) => baseField(name, presentation.textSource(label), type, autocomplete, required);
+                    const form = (action, csrf, fields, button) => postForm({ action, csrf, fields, label: presentation.textSource(button), className: 'ui-form-grid' });
+                    try {
+                        const token = http.session(request), principal = token ? await service.authenticate(token) : null;
+                        if (!token || !principal || principal.impersonatorId || !permissions.some(permission => hasPermission(principal, permission)))
+                            throw new AuthHttpError(404, 'Not found');
+                        const accountLocale = (await service.getUser(principal.id))?.profile?.locale;
+                        if (accountLocale) {
+                            preferences = { accountLocale, ...preferences };
+                            presentation = source.resolve(preferences);
+                        }
+                        const path = request.path.slice(mount.length) || '/';
+                        if (!['GET', 'HEAD', 'POST'].includes(request.method))
+                            return jsonResponse(405, { error: 'Method not allowed' }, [['allow', 'GET, HEAD, POST']]);
+                        const csrf = http.token(token), shell = navigation(principal, value => presentation.textSource(value), tr, path);
+                        const screen = (title, name, view, status, headers) => screenResponse(title, { name: 'admin/' + name, view }, { ...render(), shell, status, headers });
+                        const status = (title, message, href = null, label = null) => screen(title, 'status', { alert: false, message, href, label });
+                        const accountResult = await accounts.handle(request, principal, token, { ...render(), shell });
+                        if (accountResult)
+                            return accountResult;
+                        const recoveryResult = await recovery.handle(request, principal, token, { ...render(), shell });
+                        if (recoveryResult)
+                            return recoveryResult;
+                        if (request.method !== 'POST') {
+                            if (path === '/' || path === '/dashboard') {
+                                const granted = permissions.filter(permission => hasPermission(principal, permission));
+                                const stats = hasPermission(principal, 'auth.users.read') ? await service.dashboard() : undefined;
+                                const users = hasPermission(principal, 'auth.users.read') ? await service.listUsers({ limit: 50 }) : undefined;
+                                const methodCounts = new Map();
+                                for (const day of stats?.daily ?? [])
+                                    for (const entry of day.methods) {
+                                        const total = methodCounts.get(entry.method) ?? { signUps: 0, signIns: 0, failedSignIns: 0 };
+                                        total.signUps += entry.signUps;
+                                        total.signIns += entry.signIns;
+                                        total.failedSignIns += entry.failedSignIns;
+                                        methodCounts.set(entry.method, total);
+                                    }
+                                const recent = hasPermission(principal, 'auth.audit.read') ? await service.listAudit({ limit: 20 }) : undefined;
+                                if (wantsJson(request))
+                                    return jsonResponse(200, { permissions: granted, csrf, ...(users ? { accounts: stats, accountsShown: users.users.length, moreAccounts: !!users.next } : {}), ...(recent ? { recentEvents: recent.events } : {}) });
+                                const number = (value) => tr('number.value', { value }), counts = (total) => ({ signUps: number(total.signUps), signIns: number(total.signIns), failedSignIns: number(total.failedSignIns) });
+                                return screen('Administration', 'dashboard', {
+                                    impersonation: hasPermission(principal, 'auth.users.impersonate') && options.notifyImpersonation ? { summary: presentation.textSource('Start ten-minute support impersonation'), form: markup(form(mount + '/impersonate', csrf, formField('accountId', 'Account ID') + formField('reason', 'Reason'), 'Start ten-minute support impersonation')) } : null,
+                                    intro: tr('copy.selectASectionOnlyPermittedOperationsAreShownConfigurationRemainsInVersionControlledProjectFiles'),
+                                    summary: stats ? markup(dashboardSummary(stats, mount, principal, presentation)) : null,
+                                    activity: stats ? { heading: presentation.textSource('View activity totals'), description: tr('copy.recordedAccountCreationsSuccessfulSignInsAndFailedSignInsTheseFiguresDescribeAuthenticationActivityDeploymentH'), dailyCaption: tr('copy.dailyAuthenticationCounts'), methodsCaption: tr('copy.authenticationMethodsOverTheSame30Days'), dayHeading: tr('copy.uTCDay'), methodHeading: tr('copy.method'), signUps: tr('copy.signUps'), signIns: tr('copy.signIns'), failedSignIns: tr('copy.failedSignIns'), days: stats.daily.map(day => ({ day: day.day, ...counts(day) })), methods: [...methodCounts].map(([method, total]) => ({ method, ...counts(total) })) } : null,
+                                    recent: recent ? { heading: tr('copy.recentEvents'), auditHref: mount + '/audit', auditLabel: tr('nav.audit'), events: recent.events.slice(0, 8).map(event => ({ action: event.action, datetime: new Date(event.created).toISOString(), label: new Date(event.created).toISOString().replace('T', ' ').slice(0, 16) })), empty: presentation.textSource('No account activity recorded.') } : null,
+                                });
+                            }
+                            if (path === '/health') {
+                                requirePermission(principal, 'auth.health.read');
+                                const health = readHealth ? await readHealth() : null;
+                                if (wantsJson(request))
+                                    return jsonResponse(health || !readHealth ? 200 : 503, { configured: !!readHealth, health });
+                                const view = healthScreen({ health, configured: !!readHealth, mount, csrf, principal, presentation, query: request.query });
+                                return screenResponse('Service health', view, { ...render(), shell });
+                            }
+                            if (path === '/cases') {
+                                requirePermission(principal, 'auth.cases.read');
+                                const result = await service.listCases({ limit: 50, ...(request.query.get('after') ? { after: request.query.get('after') } : {}) });
+                                if (wantsJson(request))
+                                    return jsonResponse(200, { ...result, csrf });
+                                return screenResponse('Support cases', casesScreen({ result, mount, csrf, principal, presentation, query: request.query }), { ...render(), shell });
+                            }
+                            if (path === '/registrations') {
+                                requirePermission(principal, 'auth.users.manage');
+                                const result = await service.listRegistrationRequests({ limit: 50, ...(request.query.get('after') ? { after: request.query.get('after') } : {}) });
+                                if (wantsJson(request))
+                                    return jsonResponse(200, { ...result, requests: result.requests.map(item => ({ ...item, email: maskEmail(item.email) })), csrf });
+                                return screenResponse('Registration requests', registrationsScreen({ result, mount, csrf, principal, presentation, query: request.query, canInvite: !!options.sendInvitation }), { ...render(), shell });
+                            }
+                            if (path === '/users/detail') {
+                                requirePermission(principal, 'auth.users.read');
+                                const account = await service.getUser(request.query.get('id') || '');
+                                if (!account)
+                                    throw new AuthHttpError(404, 'Account not found');
+                                const activity = hasPermission(principal, 'auth.audit.read') ? await service.listAudit({ limit: 20, subject: account.id }) : undefined;
+                                const notes = hasPermission(principal, 'auth.audit.read') ? await service.listAudit({ limit: 50, subject: account.id, action: 'admin.note' }) : undefined;
+                                const user = { ...account, email: maskEmail(account.email) }, sessions = hasPermission(principal, 'auth.sessions.manage') ? await service.listSessions(user.id) : undefined;
+                                if (wantsJson(request))
+                                    return jsonResponse(200, { user, ...(sessions ? { sessions } : {}), ...(activity ? { activity: activity.events } : {}), csrf });
+                                return screenResponse('Account details', accountDetail({ user, principal, mount, csrf, presentation, ...(sessions ? { sessions } : {}), ...(activity ? { activity } : {}), ...(notes ? { notes } : {}), operations: accounts.enabled(), recovery: recovery.enabled() }), { ...render(), shell });
+                            }
+                            if (path === '/users') {
+                                requirePermission(principal, 'auth.users.read');
+                                const result = await service.listUsers(userFilters(request.query)), users = result.users.map(user => ({ ...user, email: maskEmail(user.email) }));
+                                if (wantsJson(request))
+                                    return jsonResponse(200, { users, ...(result.next ? { next: result.next } : {}), csrf });
+                                return screenResponse('Users', userDirectory({ users, ...(result.next ? { next: result.next } : {}), query: request.query, principal, mount, csrf, presentation, canSendSetup: !!options.sendSetup }), { ...render(), shell });
+                            }
+                            if (path === '/roles') {
+                                requirePermission(principal, 'auth.roles.read');
+                                const roles = service.getRoles();
+                                if (wantsJson(request))
+                                    return jsonResponse(200, { roles, csrf });
+                                return screenResponse('Roles', rolesScreen({ roles, mount, csrf, principal, presentation, query: request.query }), { ...render(), shell });
+                            }
+                            if (path === '/sessions') {
+                                requirePermission(principal, 'auth.sessions.manage');
+                                const result = await service.listAllSessions(sessionFilters(request.query));
+                                if (wantsJson(request))
+                                    return jsonResponse(200, { ...result, sessions: result.sessions.map(session => ({ ...session, ...('email' in session ? { email: maskEmail(String(session.email)) } : {}) })), csrf });
+                                return screenResponse('Sessions', sessionsScreen({ result, mount, csrf, principal, presentation, query: request.query }), { ...render(), shell });
+                            }
+                            if (path === '/audit/export') {
+                                requirePermission(principal, 'auth.audit.read');
+                                requirePermission(principal, 'auth.audit.export');
+                                return jsonResponse(200, await exportAuditRange(service, token, request.query), [['content-disposition', 'attachment; filename="audit-range.json"']]);
+                            }
+                            if (path === '/audit') {
+                                requirePermission(principal, 'auth.audit.read');
+                                const result = await service.listAudit(auditFilters(request.query));
+                                if (wantsJson(request))
+                                    return jsonResponse(200, result);
+                                return screenResponse('Audit', auditScreen({ result, mount, csrf, principal, presentation, query: request.query }), { ...render(), shell });
+                            }
+                            throw new AuthHttpError(404, 'Not found');
+                        }
+                        const fields = readFields(request, [...selectedNames(request.body, request.headers.get('content-type')), 'accountIds', 'confirmation', ...userFilterKeys, 'after', 'accountId', 'roles', 'status', 'reason', 'requestId', 'email', 'action', 'caseId', 'sessionId']);
+                        http.verify(request, fields);
+                        if (!fields.reason?.trim() || fields.reason.length > 256)
+                            throw new AuthHttpError(400, 'A reason is required');
+                        if (Date.now() - principal.authenticatedAt > 5 * 60 * 1000)
+                            throw new AuthHttpError(403, 'Confirm your identity before this action');
+                        if (path === '/users/note') {
+                            requirePermission(principal, 'auth.users.manage');
+                            await service.adminAddNote({ actorToken: token, accountId: fields.accountId || '', reason: fields.reason });
+                            return wantsJson(request) ? jsonResponse(200, { saved: true }) : status('Note saved', presentation.textSource('Administrator note saved.'));
+                        }
+                        if (path === '/users/bulk') {
+                            if (!['lock', 'unlock', 'revoke-sessions'].includes(fields.action || ''))
+                                throw new AuthHttpError(400, 'Invalid bulk action');
+                            const action = fields.action;
+                            requirePermission(principal, action === 'revoke-sessions' ? 'auth.sessions.manage' : 'auth.users.manage');
+                            const accountIds = selectedAccounts(fields);
+                            if (fields.confirmation !== action.toUpperCase() + ' ' + accountIds.length)
+                                throw new AuthHttpError(400, 'Typed confirmation must match the action and selected count');
+                            const result = await service.adminBulk({ actorToken: token, accountIds, action, reason: fields.reason });
+                            return wantsJson(request) ? jsonResponse(200, result) : status('Bulk update completed', tr('message.bulkUpdated', { count: result.affected }));
+                        }
+                        if (path === '/users/export-range') {
+                            requirePermission(principal, 'auth.users.export');
+                            requirePermission(principal, 'auth.users.read');
+                            const filters = new URLSearchParams();
+                            for (const key of userFilterKeys)
+                                if (fields[key])
+                                    filters.set(key, fields[key]);
+                            const body = await exportUserRange(service, token, filters, fields.reason || '');
+                            const base = jsonResponse(200, {});
+                            return { ...base, headers: [...base.headers.filter(([name]) => name !== 'content-type'), ['content-type', 'text/csv; charset=utf-8'], ['content-disposition', 'attachment; filename="accounts-filtered.csv"']], body };
+                        }
+                        if (path === '/users/export-page') {
+                            requirePermission(principal, 'auth.users.export');
+                            requirePermission(principal, 'auth.users.read');
+                            const filterValues = new URLSearchParams();
+                            for (const key of [...userFilterKeys, 'after'])
+                                if (fields[key])
+                                    filterValues.set(key, fields[key]);
+                            const page = await service.listUsers(userFilters(filterValues));
+                            const users = [];
+                            for (const user of page.users) {
+                                const exported = await service.adminExport({ actorToken: token, accountId: user.id, reason: fields.reason });
+                                users.push({ ...exported.user, ...('observedLastSeen' in user ? { observedLastSeen: user.observedLastSeen } : {}) });
+                            }
+                            const base = jsonResponse(200, {});
+                            return { ...base, headers: [...base.headers.filter(([name]) => name !== 'content-type'), ['content-type', 'text/csv; charset=utf-8'], ['content-disposition', 'attachment; filename="accounts-page.csv"'], ...(page.next ? [['x-next-cursor', page.next]] : [])], body: usersCsv(users) };
+                        }
+                        if (path === '/users/reveal') {
+                            requirePermission(principal, 'auth.users.read');
+                            requirePermission(principal, 'auth.users.reveal');
+                            const result = await service.adminReveal({ actorToken: token, accountId: fields.accountId || '', reason: fields.reason });
+                            return wantsJson(request) ? jsonResponse(200, result) : screen('Account identifier', 'reveal', { idLabel: tr('field.accountId'), id: result.id, emailLabel: tr('copy.email'), email: result.email });
+                        }
+                        if (path === '/users/export') {
+                            requirePermission(principal, 'auth.users.export');
+                            return jsonResponse(200, await service.adminExport({ actorToken: token, accountId: fields.accountId || '', reason: fields.reason }), [['content-disposition', 'attachment; filename="account-export.json"']]);
+                        }
+                        else if (path === '/users/create') {
+                            requirePermission(principal, 'auth.users.create');
+                            if (!options.sendSetup)
+                                throw new AuthHttpError(503, 'Setup delivery unavailable');
+                            const created = await service.adminCreateUser({ actorToken: token, email: fields.email || '', reason: fields.reason });
+                            await withDeadline(signal => options.sendSetup({ email: created.user.email, token: created.setupToken, signal }), 5000, 'Setup delivery timeout');
+                        }
+                        else if (path === '/sessions/revoke-one') {
+                            requirePermission(principal, 'auth.sessions.manage');
+                            await service.adminRevokeSession({ actorToken: token, sessionId: fields.sessionId || '', reason: fields.reason });
+                        }
+                        else if (path === '/cases/create') {
+                            requirePermission(principal, 'auth.cases.manage');
+                            if (!['reset-factors', 'lock', 'unlock', 'roles'].includes(fields.action || ''))
+                                throw new AuthHttpError(400, 'Invalid case action');
+                            await service.createCase({ actorToken: token, accountId: fields.accountId || '', action: fields.action, ...(fields.roles ? { roles: fields.roles.split(',').map(role => role.trim()).filter(Boolean) } : {}), reason: fields.reason });
+                        }
+                        else if (path === '/cases/note') {
+                            requirePermission(principal, 'auth.cases.manage');
+                            await service.addCaseNote({ actorToken: token, caseId: fields.caseId || '', note: fields.reason });
+                        }
+                        else if (path === '/cases/close') {
+                            requirePermission(principal, 'auth.cases.manage');
+                            await service.closeCase({ actorToken: token, caseId: fields.caseId || '', reason: fields.reason });
+                        }
+                        else if (path === '/cases/approve') {
+                            requirePermission(principal, 'auth.cases.manage');
+                            await service.approveCase({ actorToken: token, caseId: fields.caseId || '', reason: fields.reason });
+                        }
+                        else if (path === '/impersonate') {
+                            requirePermission(principal, 'auth.users.impersonate');
+                            if (!options.notifyImpersonation)
+                                throw new AuthHttpError(503, 'Impersonation notification is required');
+                            const result = await service.createImpersonation({ actorToken: token, accountId: fields.accountId || '', reason: fields.reason });
+                            try {
+                                await withDeadline(signal => options.notifyImpersonation({ email: result.user.email, actorId: principal.id, reason: fields.reason, signal }), 5000, 'Notification timeout');
+                            }
+                            catch (error) {
+                                await service.logout(result.token);
+                                throw error;
+                            }
+                            return jsonResponse(303, { impersonating: true }, [['location', authMount + '/account'], ...http.sessionHeaders(result.token)]);
+                        }
+                        else if (path === '/registrations/approve') {
+                            requirePermission(principal, 'auth.users.manage');
+                            await service.approveRegistration({ actorToken: token, requestId: fields.requestId || '', reason: fields.reason });
+                        }
+                        else if (path === '/invitations') {
+                            requirePermission(principal, 'auth.users.create');
+                            if (!options.sendInvitation)
+                                throw new AuthHttpError(503, 'Invitation delivery unavailable');
+                            const issued = await service.invite({ actorToken: token, email: fields.email || '' });
+                            await withDeadline(signal => options.sendInvitation({ email: fields.email || '', token: issued.token, signal }), 5000, 'Delivery timeout');
+                        }
+                        else if (path === '/users/roles') {
+                            requirePermission(principal, 'auth.users.manage');
+                            const roles = (fields.roles || '').split(',').map(role => role.trim()).filter(Boolean);
+                            await service.adminSetRoles({ actorToken: token, accountId: fields.accountId || '', roles, reason: fields.reason });
+                        }
+                        else if (path === '/users/status') {
+                            requirePermission(principal, 'auth.users.manage');
+                            if (fields.status !== 'active' && fields.status !== 'locked')
+                                throw new AuthHttpError(400, 'Invalid status');
+                            await service.adminSetStatus({ actorToken: token, accountId: fields.accountId || '', status: fields.status, reason: fields.reason });
+                        }
+                        else if (path === '/sessions/revoke') {
+                            requirePermission(principal, 'auth.sessions.manage');
+                            await service.adminRevokeSessions({ actorToken: token, accountId: fields.accountId || '', reason: fields.reason });
+                        }
+                        else
+                            throw new AuthHttpError(404, 'Not found');
+                        return wantsJson(request) ? jsonResponse(200, { updated: true }) : status('Update completed', tr('message.operationCompleted'), mount, presentation.textSource('Return to overview'));
+                    }
+                    catch (error) {
+                        return failureResponse(error, request, render());
+                    }
+                } };
+        } };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { initAdministration } from "./scaffold.js";
+try {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: { directory: { type: 'string' }, help: { type: 'boolean' } } });
+    if (values.help || !positionals.length)
+        process.stdout.write('urlcode-admin init --directory NEW_DIRECTORY\nCreates a private auth/admin operator host and route project. Review before activation.\n');
+    else if (positionals.length === 1 && positionals[0] === 'init' && values.directory)
+        process.stdout.write(JSON.stringify(await initAdministration(values.directory)) + '\n');
+    else
+        throw new Error('Invalid command');
+}
+catch {
+    process.stderr.write('Admin initialization failed; provide a new directory with an existing parent.\n');
+    process.exitCode = 1;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { adminExtension } from './admin.ts';
+export type { AdminExtensionOptions } from './admin.ts';
+export { initAdministration, scaffold } from './scaffold.ts';
+export type { ScaffoldRequest, ScaffoldFile, ScaffoldResult } from './scaffold.ts';
+export type { AdminHealthProvider, AdminHealthSnapshot, HealthStatus } from './admin-health.ts';
+export { withSupportBanner } from './support-banner.ts';
+export type { SupportBannerOptions } from './support-banner.ts';
+export { createAdministrationRuntime } from './admin-runtime.ts';
+export type { AdministrationRuntimeOptions } from './admin-runtime.ts';
+export { createAdminPresentation, adminCatalogue } from './admin-copy.ts';
+export { adminTemplates, adminTemplateNames, adminUiTemplates } from './admin-templates.ts';
+export type { AdminTemplate } from './admin-templates.ts';
+export type { Screen, ScreenOptions, UiHost } from './admin-ui.ts';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { adminExtension } from "./admin.js";
+export { initAdministration, scaffold } from "./scaffold.js";
+export { withSupportBanner } from "./support-banner.js";
+export { createAdministrationRuntime } from "./admin-runtime.js";
+export { createAdminPresentation, adminCatalogue } from "./admin-copy.js";
+export { adminTemplates, adminTemplateNames, adminUiTemplates } from "./admin-templates.js";

package/dist/scaffold.d.ts

@@ -0,0 +1,38 @@
+/** Shared scaffold contract (core `urlcode init --with`, auth, admin): what the caller has decided so far. */
+export interface ScaffoldRequest {
+    /** Absolute output directory the caller will create; nothing is written by `scaffold`. */
+    directory: string;
+    /** Absolute route-project directory (contains urlcode.yaml). */
+    project: string;
+    /** Absolute host module path the caller will write. */
+    hostFile: string;
+    /** Every extension name being composed, in host order. */
+    names: readonly string[];
+}
+export interface ScaffoldFile {
+    path: string;
+    content: string | Uint8Array;
+    mode?: number;
+}
+export interface ScaffoldResult {
+    name: string;
+    extensions: Record<string, unknown>;
+    routes: Record<string, unknown>;
+    hostImports: string[];
+    hostSetup: string[];
+    hostEntries: string[];
+    hostClose?: string[];
+    files: ScaffoldFile[];
+    readme: string;
+    nextSteps: string[];
+    env?: Record<string, string>;
+}
+/** Describes admin's contribution to a composed project without writing anything. Requires the auth extension in the same host. */
+export declare function scaffold(request: ScaffoldRequest): Promise<ScaffoldResult>;
+/** Separate operator host and route project; both extensions remain explicitly pinned. */
+export declare function initAdministration(directory: string): Promise<{
+    directory: string;
+    project: string;
+    hostFile: string;
+    operatorFile: string;
+}>;