tinywebui 0.1.0

package/public/themes/manifest.json

@@ -0,0 +1,6 @@
+{
+  "themes": [
+    { "id": "fall-fairy", "name": "Fall Fairy", "file": "fall-fairy/fall-fairy.css", "js": "fall-fairy/fall-fairy.js" },
+    { "id": "cyber-grid", "name": "Cyber Grid", "file": "cyber-grid/cyber-grid.css" }
+  ]
+}

package/public/themes/theme-loader.js

@@ -0,0 +1,123 @@
+/*
+ * Theme loader — the only bridge between the core app and public/themes/.
+ * Skins are pure CSS files that redefine the variables styles.css already
+ * reads; this file just knows how to list them, apply one, and remember the
+ * choice. Adding a skin means dropping a CSS file here and adding one line
+ * to manifest.json — nothing in app.js or styles.css changes.
+ *
+ * A skin may also name a `js` module. That module is the skin's own scenery:
+ * it gets mounted when the skin is selected and unmounted when it is not, and
+ * it is expected to keep to the same contract the CSS does — decorative,
+ * pointer-events:none, nothing that reads or writes app state. The loader is
+ * the only place that knows such modules exist, so a skin with one is still
+ * just a file in this directory.
+ */
+
+const KEY = 'tinywebui.theme';
+const LINK_ID = 'theme-css';
+
+/** The mounted scenery module's teardown, if the current skin brought one. */
+let unmountScene = null;
+
+async function applyTheme(id, themes) {
+  document.documentElement.dataset.theme = id || '';
+
+  // Whatever the last skin put on the page goes first, before its CSS does:
+  // a scene left running against another skin's palette is the one failure
+  // mode this bridge can actually cause.
+  if (unmountScene) {
+    try { unmountScene(); } catch { /* a broken skin must not wedge the picker */ }
+    unmountScene = null;
+  }
+
+  let link = document.getElementById(LINK_ID);
+  const t = themes.find((x) => x.id === id);
+  if (!t) {
+    if (link) link.remove();
+    return;
+  }
+  if (!link) {
+    link = document.createElement('link');
+    link.id = LINK_ID;
+    link.rel = 'stylesheet';
+    document.head.appendChild(link);
+  }
+  const loaded = cssLoaded(link, `themes/${t.file}`);
+  link.href = `themes/${t.file}`;
+
+  if (!t.js) return;
+  try {
+    // The scene reads its palette out of the skin's own custom properties, so
+    // it cannot start until that stylesheet is actually applied. Setting href
+    // and importing in the same breath loses that race: the module resolves
+    // first, every variable reads back empty, and the scene starts against a
+    // palette that does not exist yet.
+    await loaded;
+    const mod = await import(`./${t.js}`);
+    // The skin may have been switched again while its module was loading.
+    if (document.documentElement.dataset.theme !== id) return;
+    unmountScene = (await mod.mount?.()) || mod.unmount || null;
+  } catch (err) {
+    // Scenery is decoration — the skin still works as plain CSS — but a failure
+    // that leaves no trace anywhere is the one that costs an afternoon.
+    console.warn(`[theme] "${id}" scenery did not start:`, err);
+  }
+}
+
+/** Resolves when the stylesheet at `href` has applied, or when waiting any
+ *  longer stops being worth it. A skin must never hang on its own decoration,
+ *  so this resolves rather than rejects on error or timeout. */
+function cssLoaded(link, href) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = () => { if (!done) { done = true; resolve(); } };
+    link.addEventListener('load', finish, { once: true });
+    link.addEventListener('error', finish, { once: true });
+    // A stylesheet already in the cache can fire load before we listen, and a
+    // slow one must not hold the scene hostage.
+    setTimeout(finish, 2000);
+    queueMicrotask(() => {
+      for (const sheet of document.styleSheets) {
+        if (sheet.href && sheet.href.endsWith(href)) finish();
+      }
+    });
+  });
+}
+
+function savedTheme() {
+  try { return localStorage.getItem(KEY) || ''; } catch { return ''; }
+}
+
+function saveTheme(id) {
+  try {
+    if (id) localStorage.setItem(KEY, id);
+    else localStorage.removeItem(KEY);
+  } catch { /* per-viewer convenience only */ }
+}
+
+async function init() {
+  let themes = [];
+  try {
+    const res = await fetch('themes/manifest.json');
+    themes = (await res.json()).themes || [];
+  } catch { /* no manifest, no skins available this session */ }
+
+  const current = savedTheme();
+  applyTheme(current, themes);
+
+  const select = document.getElementById('theme');
+  if (!select) return;
+  for (const t of themes) {
+    const opt = document.createElement('option');
+    opt.value = t.id;
+    opt.textContent = t.name;
+    select.appendChild(opt);
+  }
+  select.value = current;
+  select.addEventListener('change', () => {
+    saveTheme(select.value);
+    applyTheme(select.value, themes);
+  });
+}
+
+init();

package/src/access/auth.js

@@ -0,0 +1,228 @@
+import { randomBytes, createHmac, createHash, timingSafeEqual, scryptSync } from 'node:crypto';
+import { BlockList, isIP } from 'node:net';
+import { resolveAccess } from './policy.js';
+import { audit } from '../audit.js';
+
+/**
+ * Session/cookie plumbing for authMode 'single' (password login), plus the
+ * identity resolution for 'trusted-header' further down.
+ * No framework, no dependency: a signed HTTP-only cookie names a session
+ * token, and the token itself is looked up (by its hash, never the raw
+ * value) against the `sessions` table. When authMode is 'none' none of this
+ * is ever called -- see auth_gate.js.
+ */
+
+const COOKIE_NAME = 'tinywebui_session';
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+/** HMAC-signs a value so a client can hold it without being able to forge it. */
+function sign(value, secret) {
+  return createHmac('sha256', secret).update(value).digest('hex');
+}
+
+function verify(value, sig, secret) {
+  const expected = sign(value, secret);
+  const a = Buffer.from(sig, 'hex');
+  const b = Buffer.from(expected, 'hex');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export function createSession(store, userId, ttlDays = 30) {
+  const token = randomBytes(32).toString('hex');
+  store.users.addSession(sha256(token), userId, Date.now() + ttlDays * 86400_000);
+  return token;
+}
+
+export function destroySession(store, token) {
+  store.users.deleteSession(sha256(token));
+}
+
+export function destroyUserSessions(store, userId) {
+  store.users.deleteUserSessions(userId);
+}
+
+/** Builds the Set-Cookie header value for a freshly created session token. */
+export function sessionCookie(token, secret, { secure = false } = {}) {
+  const signature = sign(token, secret);
+  const parts = [
+    `${COOKIE_NAME}=${token}.${signature}`,
+    'Path=/', 'HttpOnly', 'SameSite=Lax',
+  ];
+  if (secure) parts.push('Secure');
+  return parts.join('; ');
+}
+
+export function clearCookie({ secure = false } = {}) {
+  const parts = [`${COOKIE_NAME}=`, 'Path=/', 'HttpOnly', 'SameSite=Lax', 'Max-Age=0'];
+  if (secure) parts.push('Secure');
+  return parts.join('; ');
+}
+
+/* ---------- password (authMode 'single') ---------- */
+
+const SCRYPT = { N: 16384, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+
+/** `scrypt$<salt hex>$<hash hex>` -- what authPassword holds. Never plaintext. */
+export function hashPassword(password) {
+  const salt = randomBytes(16);
+  const hash = scryptSync(String(password), salt, 32, SCRYPT);
+  return `scrypt$${salt.toString('hex')}$${hash.toString('hex')}`;
+}
+
+export function verifyPassword(password, stored) {
+  const [kind, saltHex, hashHex] = String(stored || '').split('$');
+  if (kind !== 'scrypt' || !saltHex || !hashHex) return false;
+  const expected = Buffer.from(hashHex, 'hex');
+  const actual = scryptSync(String(password ?? ''), Buffer.from(saltHex, 'hex'), expected.length, SCRYPT);
+  return timingSafeEqual(actual, expected);
+}
+
+/** The raw session token from a validly signed cookie, or null. */
+export function sessionToken(req, cfg) {
+  const raw = readCookie(req);
+  if (!raw) return null;
+  const dot = raw.lastIndexOf('.');
+  if (dot === -1) return null;
+  const token = raw.slice(0, dot);
+  return cfg.sessionSecret && verify(token, raw.slice(dot + 1), cfg.sessionSecret) ? token : null;
+}
+
+function readCookie(req) {
+  const header = req.headers.cookie;
+  if (!header) return null;
+  for (const part of header.split(';')) {
+    const idx = part.indexOf('=');
+    if (idx === -1) continue;
+    const name = part.slice(0, idx).trim();
+    if (name === COOKIE_NAME) return part.slice(idx + 1).trim();
+  }
+  return null;
+}
+
+/** Whether the connection looks TLS-terminated, for the cookie's Secure flag. */
+export function isSecureRequest(req, trustedProxyCidrs = []) {
+  if (req.socket?.encrypted === true) return true;
+  // X-Forwarded-Proto is a claim only a known proxy may make.
+  return req.headers['x-forwarded-proto'] === 'https' && ipInCidrs(req.socket?.remoteAddress, trustedProxyCidrs);
+}
+
+/**
+ * Resolves the logged-in user for a request, or null. Verifies the cookie's
+ * signature first (cheap, rejects tampering/forgery), then looks up the
+ * token's hash in `sessions` and checks expiry.
+ */
+export function getSessionUser(req, store, cfg) {
+  const token = sessionToken(req, cfg);
+  if (!token) return null;
+
+  const session = store.users.getSession(sha256(token));
+  if (!session || session.expires_at < Date.now()) return null;
+
+  return store.users.get(session.user_id);
+}
+
+/* ---------- trusted-header mode ---------- */
+
+/** Parsed once per cidr list; `::ffff:1.2.3.4` peers are checked as IPv4. */
+const blockLists = new WeakMap();
+export function ipInCidrs(ip, cidrs) {
+  if (!ip || !Array.isArray(cidrs) || !cidrs.length) return false;
+  let list = blockLists.get(cidrs);
+  if (!list) {
+    list = new BlockList();
+    for (const cidr of cidrs) {
+      const [addr, bits] = String(cidr).split('/');
+      const family = isIP(addr) === 6 ? 'ipv6' : 'ipv4';
+      const prefix = bits === undefined ? (family === 'ipv6' ? 128 : 32) : Number(bits);
+      list.addSubnet(addr, prefix, family);
+    }
+    blockLists.set(cidrs, list);
+  }
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(ip);
+  if (mapped) return list.check(mapped[1], 'ipv4');
+  return list.check(ip, isIP(ip) === 6 ? 'ipv6' : 'ipv4');
+}
+
+const HEADER_ROLES = new Set(['admin', 'user']);
+const LOGIN_TOUCH_MS = 60_000;
+
+function header(req, name) {
+  const v = req.headers[String(name).toLowerCase()];
+  const s = Array.isArray(v) ? v[0] : v;
+  return typeof s === 'string' ? s.trim() : '';
+}
+
+/**
+ * Resolves (and on first sight provisions) the user an upstream gateway has
+ * vouched for. Returns { user } or { reject: reason }.
+ *
+ * Headers are believed only from a peer inside trustedProxyCidrs, judged by
+ * the socket address -- never X-Forwarded-For, which the client controls.
+ * The external id is the identity; email and name are metadata that follow
+ * the gateway. Role follows the gateway when it sends one; status is only
+ * ever set here on creation and otherwise belongs to TinyWebUI admins.
+ */
+export function resolveTrustedUser(req, store, cfg) {
+  if (!ipInCidrs(req.socket?.remoteAddress, cfg.trustedProxyCidrs)) return { reject: 'untrusted_peer' };
+  const externalId = header(req, cfg.trustedUserIdHeader).slice(0, 256);
+  if (!externalId) return { reject: 'missing_identity' };
+  const email = header(req, cfg.trustedEmailHeader).slice(0, 320).toLowerCase() || null;
+  const name = header(req, cfg.trustedNameHeader).slice(0, 200) || null;
+  const rawRole = header(req, cfg.trustedRoleHeader).toLowerCase();
+  const role = HEADER_ROLES.has(rawRole) ? rawRole : null;
+
+  const now = Date.now();
+  // Precedence: the files (bootstrapAdmins, access.users) > gateway role
+  // header > defaults. What an admin decided is in access.users, so the file
+  // outranks a gateway that still says otherwise.
+  const policy = resolveAccess(cfg);
+  const pinned = policy.bootstrapAdmins.includes(externalId)
+    ? { role: 'admin', status: 'approved' }
+    : policy.users[externalId] || {};
+  const wantRole = pinned.role || role;
+  const status = pinned.status || policy.newUsers;
+  let { user, created } = store.users.provision({ externalId, role: wantRole || 'user', status, now });
+  if (created) audit('user.provisioned', { userId: user.id, role: user.role, status: user.status });
+
+  const changes = {};
+  if (email !== user.email) {
+    // Emails are unique; one held by another account is dropped, never merged.
+    const next = email && store.users.emailTaken(email, user.id) ? null : email;
+    if (next !== user.email) changes.email = next;
+  }
+  if (name !== user.name) changes.name = name;
+  if (wantRole && wantRole !== user.role) {
+    changes.role = wantRole;
+    audit('user.role_changed', { userId: user.id, from: user.role, to: wantRole, by: pinned.role ? 'policy' : 'gateway' });
+  }
+  if (pinned.status && pinned.status !== user.status) {
+    changes.status = pinned.status;
+    audit('user.status_changed', { userId: user.id, from: user.status, to: pinned.status, by: 'policy' });
+  }
+  if (!user.last_login_at || now - user.last_login_at > LOGIN_TOUCH_MS) changes.last_login_at = now;
+  if (Object.keys(changes).length) user = store.users.sync(user.id, changes);
+  return { user };
+}
+
+/**
+ * Brings every provisioned user in line with the files' access.users and
+ * bootstrapAdmins, so a status decided in a file (a ban, say) holds even for
+ * someone who has not made a request since -- their automations included.
+ */
+export function applyAccessPolicy(store, cfg) {
+  const policy = resolveAccess(cfg);
+  const pins = { ...policy.users };
+  for (const id of policy.bootstrapAdmins) pins[id] = { role: 'admin', status: 'approved' };
+  for (const [externalId, pin] of Object.entries(pins)) {
+    const user = store.users.byExternalId(externalId);
+    if (!user) continue;
+    const role = pin.role && pin.role !== user.role ? pin.role : null;
+    const status = pin.status && pin.status !== user.status ? pin.status : null;
+    if (!role && !status) continue;
+    store.users.update(user.id, { ...(role ? { role } : {}), ...(status ? { status } : {}) });
+    audit('user.policy_applied', { userId: user.id, ...(role ? { role } : {}), ...(status ? { status } : {}) });
+  }
+}

package/src/access/auth_gate.js

@@ -0,0 +1,67 @@
+import { ALL_USERS } from '../store/index.js';
+import { featuresFor } from './policy.js';
+import { getSessionUser, resolveTrustedUser } from './auth.js';
+import { audit } from '../audit.js';
+import { FEATURE } from '../../public/shared/features.js';
+
+/** The one account behind a 'single' password. */
+export const OWNER_ID = 'owner';
+
+// Reachable without a session: the login/OAuth dance itself, plus static
+// assets so the login page can load before there's anyone to authenticate.
+const PRE_AUTH_PATHS = /^\/api\/auth\//;
+const isPreAuthPath = (pathname) => PRE_AUTH_PATHS.test(pathname) || !pathname.startsWith('/api/');
+
+// In trusted-header mode the gateway owns login and logout; these two are
+// the only /api/auth routes that exist, and both need the resolved user.
+const TRUSTED_AUTH_PATHS = new Set(['/api/auth/me', '/api/auth/logout']);
+// Still answered for a pending/disabled user, so the UI can say why.
+const STATUS_EXEMPT_PATHS = TRUSTED_AUTH_PATHS;
+
+function resolveIdentity(req, pathname, cfg, store) {
+  if (cfg.authMode === 'none') return { userId: ALL_USERS, role: null, user: null, isAdmin: true };
+  let user;
+  if (cfg.authMode === 'trusted-header') {
+    if (!pathname.startsWith('/api/')) return { userId: undefined, user: null, isAdmin: false };
+    if (pathname.startsWith('/api/auth/') && !TRUSTED_AUTH_PATHS.has(pathname)) return { notFound: true };
+    const result = resolveTrustedUser(req, store, cfg);
+    if (result.reject) {
+      audit('auth.rejected', { reason: result.reject, path: pathname });
+      return { unauthorized: true };
+    }
+    user = result.user;
+  } else {
+    user = getSessionUser(req, store, cfg);
+    if (!user) {
+      if (!isPreAuthPath(pathname)) return { unauthorized: true };
+      return { userId: undefined, user: null, isAdmin: false };
+    }
+  }
+  if (!STATUS_EXEMPT_PATHS.has(pathname) && !(cfg.authMode !== 'trusted-header' && isPreAuthPath(pathname))) {
+    if (user.status === 'disabled') return { disabled: true };
+    if (user.status !== 'approved') return { pending: true };
+  }
+  // 'single': sessions hang off OWNER_ID but data stays unowned (ALL_USERS),
+  // so switching between 'none' and 'single' never hides a chat.
+  if (cfg.authMode === 'single') return { userId: ALL_USERS, role: 'admin', user, isAdmin: true };
+  return { userId: user.id, role: user.role, user, isAdmin: user.role === 'admin' && user.status === 'approved' };
+}
+
+/**
+ * The one auth gate for the whole handler. Fails closed: with auth on, a
+ * request either resolves to a real user or carries `userId: undefined`,
+ * which every scoped store method refuses. 'none' is a single-person
+ * install and sees everything, exactly as before auth existed. A refusal
+ * comes back as one of notFound / unauthorized / disabled / pending.
+ */
+export function resolveAuth(req, pathname, cfg, store) {
+  const auth = resolveIdentity(req, pathname, cfg, store);
+  // Features come from the policy for the caller's role; nobody signed in
+  // gets none, which leaves only the routes the table marks open.
+  auth.features = auth.userId !== undefined ? featuresFor(cfg, auth.role) : new Set();
+  if (cfg.authMode === 'trusted-header' && auth.user) auth.isAdmin = auth.features.has(FEATURE.ADMIN);
+  return auth;
+}
+
+/** Who to name in the audit log for a change: the user, or 'local' (tiers 1-2). */
+export const actor = (auth) => (auth.user?.id && auth.user.id !== OWNER_ID ? auth.user.id : 'local');

package/src/access/policy.js

@@ -0,0 +1,180 @@
+import { createHash } from 'node:crypto';
+import { FEATURE } from '../../public/shared/features.js';
+
+/**
+ * Access policy: who can use which parts of TinyWebUI, declared in files.
+ *
+ * The `access` block lives in tinywebui.config.js and/or config.json:
+ *
+ *   access: {
+ *     bootstrapAdmins: ['<gateway user id>'],   // always admin, always approved
+ *     newUsers: 'approved' | 'pending',
+ *     roles: { user: { features: [...], models: [...] | '*' }, admin: { features: '*' } },
+ *     users: { '<gateway user id>': { role?, status? } }  // admin decisions, written back
+ *   }
+ *
+ * Everything here is pure: no I/O, so the server, the reload path and the CLI
+ * all validate and resolve the same way.
+ */
+
+/** Every feature a role can be granted. Each maps to UI and API routes. */
+export const FEATURES = Object.values(FEATURE);
+
+export const ROLES = ['admin', 'user'];
+export const STATUSES = ['pending', 'approved', 'disabled'];
+
+// Tier 3's out-of-the-box split: users work, admins run the place.
+const DEFAULT_ROLES = {
+  user: { features: [FEATURE.CHAT, FEATURE.ATTACHMENTS, FEATURE.IMAGES, FEATURE.SEARCH, FEATURE.FOLDERS, FEATURE.AUTOMATIONS, FEATURE.STATISTICS, FEATURE.MODEL_PICKER], models: '*' },
+  admin: { features: '*', models: '*' }
+};
+
+/**
+ * Keys that can never be written through the UI or API, whatever the lock
+ * state: the trust boundary, credentials, and the policy itself. They can
+ * still be set in either file (so `set-password` can write config.json).
+ */
+export const FILE_ONLY = new Set([
+  'authMode', 'authPassword', 'sessionSecret', 'sessionTtlDays', 'trustedProxyCidrs', 'trustedUserIdHeader',
+  'trustedEmailHeader', 'trustedNameHeader', 'trustedRoleHeader',
+  'logoutUrl', 'baseUrl', 'apiKey', 'dbPath', 'access', 'models', 'allowedOrigins', 'frozen', 'autoMigrate', 'retrieval',
+  'googleClientId', 'googleClientSecret', 'googleRedirectUri', 'adminEmails'
+]);
+
+// Never logged, never fingerprinted as values, never sent to a browser.
+export const SECRET_KEYS = new Set(['apiKey', 'authPassword', 'sessionSecret', 'googleClientSecret']);
+
+/**
+ * Merges the file's and the code's `access` blocks. Code wins per field;
+ * `users` merges per user, code winning, so admin write-back to the file can
+ * never override a user pinned in code.
+ */
+export function mergeAccess(fileAccess = {}, codeAccess = {}) {
+  const f = fileAccess && typeof fileAccess === 'object' ? fileAccess : {};
+  const c = codeAccess && typeof codeAccess === 'object' ? codeAccess : {};
+  return {
+    ...f, ...c,
+    users: { ...(f.users || {}), ...(c.users || {}) }
+  };
+}
+
+/** The effective policy, with defaults filled in, for a loaded config. */
+export function resolveAccess(cfg) {
+  const a = cfg.access || {};
+  const roles = {};
+  for (const r of ROLES) roles[r] = { ...DEFAULT_ROLES[r], ...(a.roles?.[r] || {}) };
+  return {
+    bootstrapAdmins: Array.isArray(a.bootstrapAdmins) ? a.bootstrapAdmins.map(String) : [],
+    newUsers: a.newUsers || 'approved',
+    roles,
+    users: a.users && typeof a.users === 'object' ? a.users : {}
+  };
+}
+
+const expand = (list) => new Set(list === '*' ? FEATURES : list || []);
+
+/**
+ * What a signed-in person may use. Tiers 1 and 2 are one person, who gets
+ * everything that makes sense for one person: no user management.
+ */
+export function featuresFor(cfg, role) {
+  if (cfg.authMode !== 'trusted-header') {
+    const all = new Set(FEATURES);
+    all.delete('admin'); all.delete('oversight');
+    return all;
+  }
+  return expand(resolveAccess(cfg).roles[role]?.features);
+}
+
+/** '*' or the list of model ids this role may pick. */
+export function modelsFor(cfg, role) {
+  if (cfg.authMode !== 'trusted-header') return '*';
+  const m = resolveAccess(cfg).roles[role]?.models;
+  return m === '*' || m === undefined ? '*' : m.map(String);
+}
+
+/** Every problem with a config, as readable strings. Empty means valid. */
+export function validateConfig(cfg, { env = process.env } = {}) {
+  const errors = [];
+  const mode = cfg.authMode;
+  if (mode === 'multiuser') {
+    errors.push("authMode 'multiuser' has no login flow yet; use 'trusted-header' behind a gateway for Google/Apple/SSO sign-in");
+  }
+  if (mode === 'trusted-header' && !(Array.isArray(cfg.trustedProxyCidrs) && cfg.trustedProxyCidrs.length)) {
+    errors.push("authMode 'trusted-header' requires trustedProxyCidrs: identity headers are only believed from those peers");
+  }
+  if (mode === 'single') {
+    if (cfg.authPassword && !String(cfg.authPassword).startsWith('scrypt$')) {
+      errors.push('authPassword must be a hash: run `tinywebui set-password` or set $TINYWEBUI_PASSWORD');
+    } else if (!cfg.authPassword && !env.TINYWEBUI_PASSWORD) {
+      errors.push("authMode 'single' needs a password: run `tinywebui set-password` or set $TINYWEBUI_PASSWORD");
+    }
+  }
+
+  const a = cfg.access;
+  if (a !== undefined) {
+    if (!a || typeof a !== 'object' || Array.isArray(a)) return [...errors, 'access must be an object'];
+    const known = new Set(['bootstrapAdmins', 'newUsers', 'roles', 'users']);
+    for (const k of Object.keys(a)) if (!known.has(k)) errors.push(`access.${k} is not a known setting`);
+    if (a.bootstrapAdmins !== undefined && !(Array.isArray(a.bootstrapAdmins) && a.bootstrapAdmins.every((x) => typeof x === 'string' && x))) {
+      errors.push('access.bootstrapAdmins must be a list of gateway user ids');
+    }
+    if (a.newUsers !== undefined && !['approved', 'pending'].includes(a.newUsers)) {
+      errors.push("access.newUsers must be 'approved' or 'pending'");
+    }
+    for (const [role, spec] of Object.entries(a.roles || {})) {
+      if (!ROLES.includes(role)) { errors.push(`access.roles.${role}: unknown role (known: ${ROLES.join(', ')})`); continue; }
+      if (!spec || typeof spec !== 'object') { errors.push(`access.roles.${role} must be an object`); continue; }
+      for (const k of Object.keys(spec)) {
+        if (!['features', 'models'].includes(k)) errors.push(`access.roles.${role}.${k} is not a known setting`);
+      }
+      if (spec.features !== undefined && spec.features !== '*') {
+        if (!Array.isArray(spec.features)) errors.push(`access.roles.${role}.features must be '*' or a list`);
+        else for (const f of spec.features) {
+          if (!FEATURES.includes(f)) errors.push(`access.roles.${role}.features: unknown feature "${f}" (known: ${FEATURES.join(', ')})`);
+        }
+      }
+      if (spec.models !== undefined && spec.models !== '*' && !(Array.isArray(spec.models) && spec.models.every((m) => typeof m === 'string' && m))) {
+        errors.push(`access.roles.${role}.models must be '*' or a list of model ids (catalog ids when models is set)`);
+      }
+    }
+    for (const [id, u] of Object.entries(a.users || {})) {
+      if (!u || typeof u !== 'object') { errors.push(`access.users["${id}"] must be an object`); continue; }
+      if (u.role !== undefined && !ROLES.includes(u.role)) errors.push(`access.users["${id}"].role must be one of ${ROLES.join(', ')}`);
+      if (u.status !== undefined && !STATUSES.includes(u.status)) errors.push(`access.users["${id}"].status must be one of ${STATUSES.join(', ')}`);
+    }
+  }
+  return errors;
+}
+
+/** Stable JSON: object keys sorted, so key order never changes a hash. */
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+/**
+ * A short hash of the effective config and MCP servers. Secrets count only
+ * as present/absent (their values never enter the hash), so a fingerprint can
+ * be logged and compared against a checked-in config without leaking anything.
+ */
+export function fingerprint(cfg, mcpServers = {}) {
+  const redacted = {};
+  for (const [k, v] of Object.entries(cfg)) {
+    // The session secret is operational (it is generated on first start),
+    // not policy; leaving it out keeps the CLI and the server in agreement.
+    if (k === 'sessionSecret') continue;
+    redacted[k] = SECRET_KEYS.has(k) ? Boolean(v) : v;
+  }
+  return createHash('sha256').update(canonical({ config: redacted, mcpServers })).digest('hex').slice(0, 16);
+}
+
+/** 'file-only' | 'frozen' | 'editable' -- how a key may be changed. */
+export function keyClass(key, lockedKeys) {
+  if (FILE_ONLY.has(key)) return 'file-only';
+  if (lockedKeys.has(key)) return 'frozen';
+  return 'editable';
+}

package/src/audit.js

@@ -0,0 +1,7 @@
+/**
+ * One JSON line per security-relevant event, on stdout for the deployment's
+ * log collector. Never pass content, prompts, tokens or raw header values.
+ */
+export function audit(event, fields = {}) {
+  console.log(`[tinywebui:audit] ${JSON.stringify({ ts: new Date().toISOString(), event, ...fields })}`);
+}