tinywebui 0.1.1 → 0.1.2

package/src/access/policy.js

@@ -20,6 +20,9 @@ import { FEATURE } from '../../public/shared/features.js';
 /** Every feature a role can be granted. Each maps to UI and API routes. */
 export const FEATURES = Object.values(FEATURE);
 
+/** What a signed-in user may personalise (access.customize). Model choice is the model-picker feature's. */
+export const CUSTOMIZABLE = ['theme', 'instructions'];
+
 export const ROLES = ['admin', 'user'];
 export const STATUSES = ['pending', 'approved', 'disabled'];
 
@@ -37,10 +40,16 @@ const DEFAULT_ROLES = {
 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',
+  'logoutUrl', 'dbPath', 'access', 'allowedOrigins', 'frozen', 'autoMigrate', 'retrieval',
   'googleClientId', 'googleClientSecret', 'googleRedirectUri', 'adminEmails'
 ]);
 
+/**
+ * Writable, but where credentials and routing live: in a multi-user
+ * deployment only an admin may send these, whatever features a role has.
+ */
+export const SECRET_PATCH_KEYS = new Set(['baseUrl', 'apiKey', 'models', 'connectors']);
+
 // Never logged, never fingerprinted as values, never sent to a browser.
 export const SECRET_KEYS = new Set(['apiKey', 'authPassword', 'sessionSecret', 'googleClientSecret']);
 
@@ -66,6 +75,7 @@ export function resolveAccess(cfg) {
   return {
     bootstrapAdmins: Array.isArray(a.bootstrapAdmins) ? a.bootstrapAdmins.map(String) : [],
     newUsers: a.newUsers || 'approved',
+    customize: Array.isArray(a.customize) ? a.customize : ['theme'],
     roles,
     users: a.users && typeof a.users === 'object' ? a.users : {}
   };
@@ -93,6 +103,8 @@ export function modelsFor(cfg, role) {
   return m === '*' || m === undefined ? '*' : m.map(String);
 }
 
+export const MIN_PASSWORD_LENGTH = 15;
+
 /** Every problem with a config, as readable strings. Empty means valid. */
 export function validateConfig(cfg, { env = process.env } = {}) {
   const errors = [];
@@ -104,17 +116,19 @@ export function validateConfig(cfg, { env = process.env } = {}) {
     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$')) {
+    if (cfg.authPassword && !/^scrypt\$[0-9a-f]{32}\$[0-9a-f]{64}$/i.test(String(cfg.authPassword))) {
       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");
+    } else if (!cfg.authPassword && env.TINYWEBUI_PASSWORD.length < MIN_PASSWORD_LENGTH) {
+      errors.push(`TINYWEBUI_PASSWORD needs at least ${MIN_PASSWORD_LENGTH} characters`);
     }
   }
 
   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']);
+    const known = new Set(['bootstrapAdmins', 'newUsers', 'roles', 'users', 'customize']);
     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');
@@ -122,6 +136,9 @@ export function validateConfig(cfg, { env = process.env } = {}) {
     if (a.newUsers !== undefined && !['approved', 'pending'].includes(a.newUsers)) {
       errors.push("access.newUsers must be 'approved' or 'pending'");
     }
+    if (a.customize !== undefined && !(Array.isArray(a.customize) && a.customize.every((c) => CUSTOMIZABLE.includes(c)))) {
+      errors.push(`access.customize must be a list from ${CUSTOMIZABLE.join(', ')}`);
+    }
     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; }
@@ -169,6 +186,9 @@ export function fingerprint(cfg, mcpServers = {}) {
     if (k === 'sessionSecret') continue;
     redacted[k] = SECRET_KEYS.has(k) ? Boolean(v) : v;
   }
+  if (Array.isArray(redacted.connectors)) {
+    redacted.connectors = redacted.connectors.map((c) => (c && typeof c === 'object' ? { ...c, apiKey: Boolean(c.apiKey) } : c));
+  }
   return createHash('sha256').update(canonical({ config: redacted, mcpServers })).digest('hex').slice(0, 16);
 }
 

package/src/chat/runs.js

@@ -43,7 +43,7 @@ export function createRuns(app) {
    * `lead` is a queued follow-up that starts this run: stored after baseCount
    * and sent as an event, so a live view and a reload each show it once.
    */
-  function start({ chat, tools, onFinish, historyFromSeq = null, unattended = false, model = null, lead = null }) {
+  function start({ chat, tools, onFinish, historyFromSeq = null, unattended = false, model = null, lead = null, instructions = null }) {
     const run = {
       events: [],
       subs: new Set(),
@@ -127,7 +127,12 @@ export function createRuns(app) {
 
     run.promise = (async () => {
       try {
-        await runChat({ cfg: effectiveConfig(app.cfg, model), chatId: chat.id, store, tools, hub: app.hub, emit, signal: run.ac.signal, historyFromSeq, unattended, approve, takeInput, askUser });
+        const base = effectiveConfig(app.cfg, model);
+        const cfg = instructions ? { ...base, systemPrompt: `${base.systemPrompt}
+
+The user's own instructions:
+${instructions}` } : base;
+        await runChat({ cfg, chatId: chat.id, store, tools, hub: app.hub, emit, signal: run.ac.signal, historyFromSeq, unattended, approve, takeInput, askUser });
       } catch (err) {
         emit({ type: EVENT.ERROR, error: run.ac.signal.aborted ? 'Stopped.' : err.message });
       } finally {

package/src/cli.js

@@ -4,10 +4,10 @@ import { pipeline } from 'node:stream/promises';
 import { dirname, join } from 'node:path';
 import { PRESETS, resolveModel, findOnnxFile, sha256File, resolveRetrieval, defaultModelsDir } from './retrieval/embedding.js';
 import { createConfigSource, DEFAULTS, WRITABLE, configProblems } from './config/config.js';
-import { REASONING_REPLAY } from './config/models.js';
+import { REASONING_REPLAY, MODEL_TAGS } from './config/models.js';
 import {
   validateConfig, fingerprint, featuresFor, modelsFor, resolveAccess, keyClass,
-  FEATURES, ROLES, STATUSES, FILE_ONLY, SECRET_KEYS
+  FEATURES, ROLES, STATUSES, FILE_ONLY, SECRET_KEYS, CUSTOMIZABLE
 } from './access/policy.js';
 import { Store, SCHEMA_VERSION, MigrationRequiredError } from './store/index.js';
 
@@ -426,8 +426,16 @@ export function configSchema() {
     }
   };
   const num = { type: ['number', 'null'] };
+  properties.connectors = {
+    type: 'array', 'x-change': 'editable (UI writes it back here)',
+    description: 'Named endpoints a catalog entry can use. apiKey is a secret: prefer an env var in committed config.',
+    items: {
+      type: 'object', additionalProperties: false, required: ['id', 'baseUrl'],
+      properties: { id: { type: 'string' }, label: { type: 'string' }, baseUrl: { type: 'string' }, apiKey: { type: 'string' } }
+    }
+  };
   properties.models = {
-    type: 'array', 'x-change': 'file-only',
+    type: 'array', 'x-change': 'editable (UI writes it back here)',
     description: 'The model catalog. Empty: any model id. Listed: only these can be picked, by id, shown by label.',
     items: {
       type: 'object', additionalProperties: false, required: ['id'],
@@ -437,6 +445,8 @@ export function configSchema() {
         label: { type: 'string', description: 'What people see in the picker.' },
         description: { type: 'string' },
         enabled: { type: 'boolean', description: 'false: keep the settings, hide and refuse the model.' },
+        connector: { type: 'string', description: 'Id of an entry in connectors; absent: the default baseUrl/apiKey.' },
+        tags: { type: 'array', items: { enum: MODEL_TAGS }, uniqueItems: true, description: 'What the model can do.' },
         systemPrompt: { type: 'string' },
         temperature: num,
         maxTokens: num,
@@ -453,6 +463,7 @@ export function configSchema() {
     properties: {
       bootstrapAdmins: { type: 'array', items: { type: 'string' }, description: 'Gateway user ids that are always approved admins.' },
       newUsers: { enum: ['approved', 'pending'] },
+      customize: { type: 'array', items: { enum: CUSTOMIZABLE }, uniqueItems: true, description: 'What users may personalise.' },
       roles: { type: 'object', additionalProperties: false, properties: Object.fromEntries(ROLES.map((r) => [r, role])) },
       users: {
         type: 'object',

package/src/config/approval.js

@@ -13,7 +13,9 @@
  *   'off'     never ask
  *
  * Built-in tools (expand_context, read_document, manage_automation) are the
- * harness's own and always run; everything here applies to MCP tools.
+ * harness's own and always run; everything here applies to MCP tools. The one
+ * exception is a built-in that edits the MCP servers themselves (manage_mcp):
+ * it is gated, and asks before any call that changes something.
  *
  * Per-tool overrides win over the mode: `confirmTools` always asks,
  * `autoApproveTools` never does.
@@ -24,7 +26,12 @@ export const APPROVAL_MODES = ['writes', 'all', 'off'];
 export function approvalFor(cfg, hub, name, args) {
   // The harness's own tools are part of the harness, not third-party code:
   // they never ask, whatever the mode or overrides say. Approval is for MCP.
-  if (hub?.isLocal?.(name)) return 'auto';
+  if (hub?.isLocal?.(name)) {
+    if (!hub.isGated?.(name, args)) return 'auto';
+    // manage_mcp can add a server that runs a command on this machine, so it
+    // asks even when the mode is 'off'. Only an explicit per-tool "auto" skips it.
+    return (cfg.autoApproveTools || []).includes(name) ? 'auto' : 'ask';
+  }
   if ((cfg.confirmTools || []).includes(name)) return 'ask';
   if ((cfg.autoApproveTools || []).includes(name)) return 'auto';
   // Missing means off, not the config default: a caller that builds its own

package/src/config/config.js

@@ -1,8 +1,8 @@
-import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, chmodSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { FILE_ONLY, mergeAccess, keyClass, validateConfig } from '../access/policy.js';
-import { modelProblems, labelFor, REASONING_REPLAY } from './models.js';
+import { modelProblems, connectorProblems, labelFor, REASONING_REPLAY } from './models.js';
 import { logger } from '../log.js';
 
 const log = logger('config');
@@ -26,6 +26,9 @@ export const DEFAULTS = {
   // only these can be picked, `model` names one by id, and people see each
   // entry's label, with its own prompt and sampling settings if it has them.
   models: [],
+  // Named endpoints a catalog entry can point at (`connector: <id>`): each has
+  // its own baseUrl and apiKey. Entries without one use baseUrl/apiKey above.
+  connectors: [],
   systemPrompt: [
     'You are a direct, technically precise assistant.',
     '',
@@ -140,15 +143,13 @@ export const DEFAULTS = {
   // is offered to the model; a server can still be reached by name, so this
   // is a per-tool block, not a substitute for disabling the whole server.
   disabledTools: [],
-  // Optional auth/RBAC. Off by default -- TinyWebUI stays single-user and
-  // local-first unless this is deliberately opted into for a managed deploy.
-  //   'none'           no login: just you, on localhost (default)
+  //   'none'           explicit local-only use without login
   //   'single'         just you, behind a password (authPassword or
   //                    $TINYWEBUI_PASSWORD; set it with `tinywebui set-password`)
   //   'trusted-header' many users: an upstream gateway (Cloudflare Access,
   //                    oauth2-proxy, Authelia, ...) signs people in with
   //                    Google, Apple, SSO etc. and passes identity headers
-  authMode: 'none',
+  authMode: 'single',
   // Level 'single': an scrypt hash (never plaintext), from `tinywebui
   // set-password`; never writable through /api/config.
   authPassword: '',
@@ -246,7 +247,8 @@ export function createConfigSource(opts = {}) {
   };
   const writeFile = (obj) => {
     if (!file) { memory = obj; return; }
-    writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
+    if (existsSync(file) && process.platform !== 'win32') chmodSync(file, 0o600);
+    writeFileSync(file, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
   };
 
   function load({ persistSecret = true } = {}) {
@@ -290,7 +292,7 @@ export function createConfigSource(opts = {}) {
     const blocked = Object.keys(patch).filter((k) => WRITABLE.has(k) && locked.has(k));
     if (blocked.length) throw new LockedError(`set in code, not editable here: ${blocked.join(', ')}`);
     const current = readFile();
-    for (const [k, v] of Object.entries(patch)) {
+    for (const [k, v] of Object.entries(mergeSecrets(patch, current))) {
       if (WRITABLE.has(k)) current[k] = v;
     }
     // Validate what the file would become before writing it.
@@ -420,7 +422,7 @@ export function configProblems(cfg) {
       if (!ENUMS[key].includes(value)) problems.push(`${key} must be one of ${ENUMS[key].join(', ')} (got ${JSON.stringify(value)})`);
       continue;
     }
-    if (key === 'models') continue; // modelProblems, below, knows the shape
+    if (key === 'models' || key === 'connectors') continue; // modelProblems/connectorProblems, below, know the shape
     if (key === 'retrieval') {
       problems.push(...retrievalProblems(value));
       continue;
@@ -446,7 +448,7 @@ export function configProblems(cfg) {
       : got === want;
     if (!ok) problems.push(`${key} must be ${want === 'null' ? 'a number or null' : `a${want === 'array' || want === 'object' ? 'n' : ''} ${want}`} (got ${got})`);
   }
-  return [...problems, ...modelProblems(cfg), ...validateConfig(cfg)];
+  return [...problems, ...connectorProblems(cfg), ...modelProblems(cfg), ...validateConfig(cfg)];
 }
 
 // Only the knobs the UI is allowed to change. Secrets stay server-side.
@@ -454,13 +456,54 @@ export const WRITABLE = new Set([
   'model', 'systemPrompt', 'temperature', 'maxTokens', 'maxToolRounds', 'askUserTimeoutSeconds',
   'cacheTtl', 'cacheMode', 'compactThreshold', 'keepTurns', 'maxInlineChars',
   'compactMinSaved', 'maxTurnChars', 'maxHistoryTokens', 'timezone',
-  'toolApproval', 'confirmTools', 'autoApproveTools', 'disabledTools'
+  'toolApproval', 'confirmTools', 'autoApproveTools', 'disabledTools',
+  // The deployment's endpoints and catalog: only the sole user or an admin may
+  // send these (see SECRET_PATCH_KEYS in policy.js); keys are write-only.
+  'baseUrl', 'apiKey', 'models', 'connectors',
+  'llmCompaction', 'compactionMaxTokens', 'expandCharBudget', 'cache', 'reasoningReplay', 'extraBody'
 ]);
 
+// A short tail is enough to tell two keys apart in a list; short keys show none.
+const keyHint = (key) => (key && key.length >= 12 ? key.slice(-4) : null);
+
+/**
+ * API keys are write-only: the page learns that one is set (and its last four
+ * characters), never the value. On save, a connector sent without `apiKey`
+ * keeps its stored key; `apiKey: null` clears it.
+ */
+export function mergeSecrets(patch, current) {
+  const out = { ...patch };
+  if ('apiKey' in out && (out.apiKey === undefined || out.apiKey === '')) delete out.apiKey;
+  else if (out.apiKey === null) out.apiKey = '';
+  if (Array.isArray(out.connectors)) {
+    const old = new Map((Array.isArray(current.connectors) ? current.connectors : []).map((c) => [c?.id, c]));
+    out.connectors = out.connectors.map((c) => {
+      if (!c || typeof c !== 'object') return c;
+      const { apiKey, ...rest } = c;
+      if (apiKey === null) return { ...rest, apiKey: '' };
+      if (apiKey === undefined || apiKey === '') return old.get(c.id)?.apiKey ? { ...rest, apiKey: old.get(c.id).apiKey } : rest;
+      return c;
+    });
+  }
+  return out;
+}
+
+/** The patch as it may be logged: secret values replaced by whether they were set. */
+export function redactSecrets(patch) {
+  const out = { ...patch };
+  if ('apiKey' in out) out.apiKey = Boolean(out.apiKey);
+  if (Array.isArray(out.connectors)) {
+    out.connectors = out.connectors.map((c) => (c && typeof c === 'object' && 'apiKey' in c ? { ...c, apiKey: Boolean(c.apiKey) } : c));
+  }
+  return out;
+}
+
 export function publicConfig(cfg) {
-  const { apiKey, authPassword, sessionSecret, googleClientSecret, ...rest } = cfg;
+  const { apiKey, authPassword, sessionSecret, googleClientSecret, connectors, ...rest } = cfg;
   return {
     ...rest,
+    connectors: (Array.isArray(connectors) ? connectors : []).map(({ apiKey: key, ...c }) => ({ ...c, hasApiKey: Boolean(key), keyHint: keyHint(key) })),
+    keyHint: keyHint(apiKey),
     modelLabel: labelFor(cfg, cfg.model),
     hasApiKey: Boolean(apiKey),
     hasGoogleAuth: Boolean(cfg.googleClientId),

package/src/config/models.js

@@ -23,7 +23,14 @@ export const MODEL_OVERRIDES = ['systemPrompt', 'temperature', 'maxTokens', 'max
 /** Values of `reasoningReplay`; see reasoningReplay in harness/provider.js. */
 export const REASONING_REPLAY = ['auto', 'omit', 'reasoning_content', 'reasoning_details'];
 
-const ENTRY_KEYS = new Set(['id', 'model', 'label', 'description', 'enabled', ...MODEL_OVERRIDES]);
+/** What a model can do; the page uses these (e.g. `vision` gates image upload). */
+export const MODEL_TAGS = ['vision', 'reasoning', 'tools'];
+
+const ENTRY_KEYS = new Set(['id', 'model', 'label', 'description', 'enabled', 'connector', 'tags', ...MODEL_OVERRIDES]);
+
+/** Named endpoints: { id, label?, baseUrl, apiKey? }. The top-level baseUrl/apiKey stay the implicit default. */
+export const connectors = (cfg) => (Array.isArray(cfg.connectors) ? cfg.connectors : []);
+export const findConnector = (cfg, id) => connectors(cfg).find((c) => c.id === id) || null;
 
 export const catalog = (cfg) => (Array.isArray(cfg.models) ? cfg.models : []);
 // Closed whenever entries are listed, even if all are disabled: parking every
@@ -44,7 +51,7 @@ export function labelFor(cfg, key) {
 }
 
 /** What the picker lists for one entry. Prompts and knobs stay server-side. */
-export const publicEntry = (e) => ({ id: e.id, name: e.label || e.id, description: e.description || null });
+export const publicEntry = (e) => ({ id: e.id, name: e.label || e.id, description: e.description || null, tags: e.tags || [] });
 
 /**
  * The config one turn runs with: the entry's overrides over the global
@@ -63,6 +70,38 @@ export function effectiveConfig(cfg, key) {
     out.extraBody.provider = { ...(cfg.extraBody?.provider || {}), ...(e.extraBody?.provider || {}) };
   }
   out.model = e.model || e.id;
+  // The entry's endpoint replaces the global one; provider.js only ever reads
+  // cfg.baseUrl and cfg.apiKey, so nothing downstream knows about connectors.
+  const conn = e.connector ? findConnector(cfg, e.connector) : null;
+  if (conn) {
+    out.baseUrl = String(conn.baseUrl).replace(/\/+$/, '');
+    out.apiKey = conn.apiKey || '';
+  }
+  return out;
+}
+
+/** Every problem with the connector list. */
+export function connectorProblems(cfg) {
+  const list = cfg.connectors;
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) return ['connectors must be a list of { id, baseUrl, apiKey?, label? } entries'];
+  const out = [];
+  const ids = new Set();
+  list.forEach((c, i) => {
+    const at = `connectors[${i}]`;
+    if (!c || typeof c !== 'object' || Array.isArray(c)) { out.push(`${at} must be an object`); return; }
+    if (typeof c.id !== 'string' || !c.id.trim()) { out.push(`${at}.id must be a non-empty string`); return; }
+    if (ids.has(c.id)) out.push(`${at}.id "${c.id}" is listed twice`);
+    ids.add(c.id);
+    for (const k of Object.keys(c)) if (!['id', 'label', 'baseUrl', 'apiKey'].includes(k)) out.push(`${at}.${k} is not a known setting (known: id, label, baseUrl, apiKey)`);
+    for (const k of ['label', 'apiKey']) if (c[k] !== undefined && typeof c[k] !== 'string') out.push(`${at}.${k} must be a string`);
+    try {
+      if (!/^https?:$/.test(new URL(c.baseUrl).protocol)) throw new Error('scheme');
+    } catch { out.push(`${at}.baseUrl must be an http(s) URL`); }
+  });
+  for (const [i, e] of (Array.isArray(cfg.models) ? cfg.models : []).entries()) {
+    if (e?.connector !== undefined && !ids.has(e.connector)) out.push(`models[${i}].connector "${e.connector}" is not in connectors`);
+  }
   return out;
 }
 
@@ -93,6 +132,8 @@ export function modelProblems(cfg) {
     if (e.reasoningReplay !== undefined && !REASONING_REPLAY.includes(e.reasoningReplay)) out.push(`${at}.reasoningReplay must be one of ${REASONING_REPLAY.join(', ')}`);
     if (e.cacheTtl !== undefined && !['5m', '1h'].includes(e.cacheTtl)) out.push(`${at}.cacheTtl must be 5m or 1h`);
     if (e.enabled !== undefined && typeof e.enabled !== 'boolean') out.push(`${at}.enabled must be true or false`);
+    if (e.connector !== undefined && typeof e.connector !== 'string') out.push(`${at}.connector must be a connector id`);
+    if (e.tags !== undefined && !(Array.isArray(e.tags) && e.tags.every((t) => MODEL_TAGS.includes(t)))) out.push(`${at}.tags must be a list from ${MODEL_TAGS.join(', ')}`);
     if (e.extraBody !== undefined && !(e.extraBody && typeof e.extraBody === 'object' && !Array.isArray(e.extraBody))) out.push(`${at}.extraBody must be an object`);
   });
   if (!list.length || out.length) return out;

package/src/mcp.js

@@ -13,7 +13,25 @@ const MAX_NAME = 64;
 
 // Built-in tools registered after connect(). An MCP tool that flattened onto
 // one of these would be shadowed by the local handler without a word.
-const RESERVED = new Set(['expand_context', 'read_document', 'manage_automation', 'ask_user', 'manage_tasks', 'search_chats']);
+const RESERVED = new Set(['expand_context', 'read_document', 'manage_automation', 'ask_user', 'manage_tasks', 'search_chats', 'manage_mcp']);
+
+const REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/**
+ * Fills `${NAME}` from the environment, so a key can live outside mcp.json (and
+ * out of any chat that set the server up). A name that is not set fails the
+ * connection with its name, never a silent empty string: an empty bearer token
+ * reads as "unauthorised" and sends people looking in the wrong place.
+ */
+export function expandRefs(value, env = process.env) {
+  if (typeof value !== 'string') return value;
+  return value.replace(REF, (_, name) => {
+    if (env[name] === undefined) throw new Error(`mcp.json refers to \${${name}}, which is not set in TinyWebUI's environment`);
+    return env[name];
+  });
+}
+
+const expandAll = (obj) => obj && Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expandRefs(v)]));
 
 /**
  * The flat name the model sees for a server's tool. Sanitising and the
@@ -87,8 +105,8 @@ function transportFor(name, spec) {
   if (spec.command) {
     return new StdioClientTransport({
       command: spec.command,
-      args: spec.args || [],
-      env: { ...process.env, ...(spec.env || {}) },
+      args: (spec.args || []).map((a) => expandRefs(a)),
+      env: { ...process.env, ...(expandAll(spec.env) || {}) },
       cwd: spec.cwd,
       // Piped rather than inherited so we can label it and, more importantly,
       // drop the shutdown noise -- a stdio server killed by Ctrl-C prints a full
@@ -97,8 +115,8 @@ function transportFor(name, spec) {
     });
   }
   if (spec.url) {
-    const opts = spec.headers ? { requestInit: { headers: spec.headers } } : undefined;
-    const url = new URL(spec.url);
+    const opts = spec.headers ? { requestInit: { headers: expandAll(spec.headers) } } : undefined;
+    const url = new URL(expandRefs(spec.url));
     return spec.transport === 'sse'
       ? new SSEClientTransport(url, opts)
       : new StreamableHTTPClientTransport(url, opts);
@@ -126,6 +144,9 @@ export class McpHub {
     // default policy: name -> true, or a function of the call's arguments.
     // Same opt-in rule -- silence means "may write".
     this.readOnly = new Map();
+    // Local tools that change the deployment itself and so ask every time,
+    // unlike the other built-ins: name -> true, or a function of the arguments.
+    this.gated = new Map();
     // Explicit 'parallel' | 'sequential' overrides for tools whose safety to
     // run alongside others is known better than the hints above say.
     this.modes = new Map();
@@ -142,8 +163,9 @@ export class McpHub {
    * Registered after connect() so locals always land at the end of the block,
    * keeping the tool list byte-identical between runs.
    */
-  registerLocal(def, handler, { readOnly = false, idempotent = readOnly === true, executionMode = null } = {}) {
+  registerLocal(def, handler, { readOnly = false, idempotent = readOnly === true, executionMode = null, gated = false } = {}) {
     this.locals.set(def.function.name, handler);
+    if (gated) this.gated.set(def.function.name, gated);
     if (executionMode) this.modes.set(def.function.name, executionMode);
     if (readOnly) this.readOnly.set(def.function.name, readOnly);
     if (idempotent) this.idempotent.add(def.function.name);
@@ -335,6 +357,12 @@ export class McpHub {
     return this.locals.has(flatName);
   }
 
+  /** True when this call is to a local tool that must ask, whatever the approval mode. */
+  isGated(flatName, args) {
+    const v = this.gated.get(flatName);
+    return typeof v === 'function' ? Boolean(v(args || {})) : Boolean(v);
+  }
+
   /** True when this call is declared to change nothing. */
   isReadOnly(flatName, args) {
     const v = this.readOnly.get(flatName);

package/src/routes/admin.js

@@ -1,6 +1,7 @@
 import { json, readJson } from '../http.js';
 import { ALL_USERS, toView } from '../store/index.js';
-import { validateConfig, fingerprint, resolveAccess } from '../access/policy.js';
+import { validateConfig, fingerprint, resolveAccess, FEATURES, CUSTOMIZABLE } from '../access/policy.js';
+import { catalog, modelProblems } from '../config/models.js';
 import { destroyUserSessions } from '../access/auth.js';
 import { audit } from '../audit.js';
 import { FEATURE } from '../../public/shared/features.js';
@@ -77,6 +78,42 @@ export function adminRoutes({ config, multiUser, refreshConfig, runs, source, st
       return json(res, 200, { user: adminUserView(updated) });
     }) },
 
+    // What the `user` role may do, what new users start as, and what users may
+    // personalise. The admin role is not editable here: it cannot be locked
+    // out of the panel that edits it. Written to the file like every decision.
+    { method: 'GET', path: /^\/api\/admin\/policy$/, feature: FEATURE.ADMIN, handle: multi(({ res }) => {
+      const a = resolveAccess(config());
+      return json(res, 200, {
+        features: FEATURES, customizable: CUSTOMIZABLE, models: catalog(config()).map((m) => m.id),
+        user: a.roles.user, newUsers: a.newUsers, customize: a.customize,
+        locked: source.lockedKeys().has('access')
+      });
+    }) },
+
+    { method: 'POST', path: /^\/api\/admin\/policy$/, feature: FEATURE.ADMIN, handle: multi(async ({ req, res, auth }) => {
+      if (source.isFrozen() || source.lockedKeys().has('access')) return json(res, 409, { error: 'access is set in code or frozen: change the files instead' });
+      const { features, models, newUsers, customize } = await readJson(req);
+      const file = source.readFile();
+      const access = file.access && typeof file.access === 'object' ? file.access : {};
+      const user = { ...(access.roles?.user || {}) };
+      if (features !== undefined) user.features = features;
+      if (models !== undefined) user.models = models;
+      const merged = {
+        ...access,
+        roles: { ...(access.roles || {}), user },
+        ...(newUsers !== undefined ? { newUsers } : {}),
+        ...(customize !== undefined ? { customize } : {})
+      };
+      const next = { ...file, access: merged };
+      const problems = [...validateConfig({ ...config(), access: merged }), ...modelProblems({ ...config(), access: merged })];
+      if (problems.length) return json(res, 400, { error: problems.join('; ') });
+      source.writeFile(next);
+      refreshConfig();
+      audit('admin.policy_changed', { by: auth.userId, user, newUsers: merged.newUsers ?? null, customize: merged.customize ?? null });
+      const a = resolveAccess(config());
+      return json(res, 200, { user: a.roles.user, newUsers: a.newUsers, customize: a.customize });
+    }) },
+
     // Oversight: read-only, every view audited. Reached through ALL_USERS on
     // purpose -- this is the one place a user's scope is crossed, and it only
     // exists when there are users to cross between.

package/src/routes/auth.js

@@ -1,6 +1,6 @@
 import { json, readJson } from '../http.js';
 import { isClosed, findEntry, labelFor } from '../config/models.js';
-import { modelsFor, fingerprint } from '../access/policy.js';
+import { modelsFor, fingerprint, resolveAccess } from '../access/policy.js';
 import {
   verifyPassword, createSession, destroySession, sessionToken, sessionCookie, clearCookie, isSecureRequest
 } from '../access/auth.js';
@@ -24,10 +24,15 @@ export function authRoutes({ config, modelFor, multiUser, passwordHash, source,
         authMode: cfg.authMode,
         logoutUrl: cfg.logoutUrl || '',
         isAdmin: Boolean(auth.isAdmin),
+        // What this person may personalise, and their saved instructions (multi-user only).
+        customize: cfg.authMode === 'trusted-header' && auth.user ? resolveAccess(cfg).customize : [],
+        instructions: cfg.authMode === 'trusted-header' && auth.user ? store.users.getPrefs(auth.user.id).instructions || '' : '',
         features: [...auth.features],
         models: signedIn ? modelsFor(cfg, auth.role) : [],
         model,
         modelLabel: signedIn ? labelFor(cfg, model) : null,
+        // What the catalog says this model can do; empty when it says nothing.
+        modelTags: signedIn ? findEntry(cfg, model)?.tags || [] : [],
         user: auth.user
           ? { id: auth.user.id, email: auth.user.email, name: auth.user.name ?? null, role: auth.user.role, status: auth.user.status }
           : null
@@ -71,10 +76,17 @@ export function authRoutes({ config, modelFor, multiUser, passwordHash, source,
 
     // Tier 3's model pill: a personal choice among the role's models. In
     // tiers 1-2 the pill changes the configured model instead (/api/config).
-    { method: 'POST', path: /^\/api\/me\/prefs$/, feature: FEATURE.MODEL_PICKER, handle: async ({ req, res, auth }) => {
+    { method: 'POST', path: /^\/api\/me\/prefs$/, feature: null, handle: async ({ req, res, auth }) => {
       const cfg = config();
       if (!multiUser()) return json(res, 400, { error: 'preferences are per-user; set the model in settings' });
-      const { model } = await readJson(req);
+      const { model, instructions } = await readJson(req);
+      if (instructions !== undefined) {
+        if (!resolveAccess(cfg).customize.includes('instructions')) return json(res, 403, { error: 'your administrator has not enabled personal instructions' });
+        if (instructions !== null && (typeof instructions !== 'string' || instructions.length > 4000)) return json(res, 400, { error: 'instructions must be text of at most 4000 characters, or null' });
+        store.users.setPref(auth.user.id, 'instructions', instructions && instructions.trim() ? instructions.trim() : null);
+        if (model === undefined) return json(res, 200, { instructions: instructions && instructions.trim() ? instructions.trim() : '' });
+      }
+      if (!auth.features.has(FEATURE.MODEL_PICKER)) return json(res, 403, { error: 'feature not available to your role', feature: FEATURE.MODEL_PICKER });
       if (model !== null && (typeof model !== 'string' || !model.trim())) return json(res, 400, { error: 'model must be a model id or null' });
       const allowed = modelsFor(cfg, auth.role);
       if (model && isClosed(cfg) && !findEntry(cfg, model)) return json(res, 403, { error: 'that model is not available to you' });

package/src/routes/chats.js

@@ -17,7 +17,7 @@ function refusedFeature(auth, { images, documentIds }) {
   return null;
 }
 
-export function chatRoutes({ config, modelFor, runs, saveConfig, store, toolsFor }) {
+export function chatRoutes({ config, instructionsFor, modelFor, runs, saveConfig, store, toolsFor }) {
   const noChat = (res) => json(res, 404, { error: 'no such chat' });
 
   return [
@@ -105,7 +105,7 @@ export function chatRoutes({ config, modelFor, runs, saveConfig, store, toolsFor
       // rewound transcript and then attaches, the same path a reload takes,
       // rather than reading a stream through a response it also has to
       // redraw behind.
-      runs.start({ chat: found, tools: toolsFor(auth.features), model: modelFor(auth.user?.id, auth.role) });
+      runs.start({ chat: found, tools: toolsFor(auth.features), model: modelFor(auth.user?.id, auth.role), instructions: instructionsFor(auth.user?.id) });
       return json(res, 200, { ok: true, running: true });
     } },
 
@@ -225,7 +225,7 @@ export function chatRoutes({ config, modelFor, runs, saveConfig, store, toolsFor
       const existing = runs.get(chat.id);
       const run = existing && !existing.done
         ? existing
-        : runs.start({ chat, tools: toolsFor(auth.features), model: modelFor(auth.user?.id, auth.role) });
+        : runs.start({ chat, tools: toolsFor(auth.features), model: modelFor(auth.user?.id, auth.role), instructions: instructionsFor(auth.user?.id) });
       return runs.attach(run, res, 0);
     } }
   ];