tinywebui 0.1.0

package/src/routes/auth.js

@@ -0,0 +1,97 @@
+import { json, readJson } from '../http.js';
+import { isClosed, findEntry, labelFor } from '../config/models.js';
+import { modelsFor, fingerprint } from '../access/policy.js';
+import {
+  verifyPassword, createSession, destroySession, sessionToken, sessionCookie, clearCookie, isSecureRequest
+} from '../access/auth.js';
+import { audit } from '../audit.js';
+import { OWNER_ID } from '../access/auth_gate.js';
+import { FEATURE } from '../../public/shared/features.js';
+
+// Failed logins per client address: 5 misses locks that address out for 15 minutes.
+const LOGIN_MAX = 5;
+const LOGIN_WINDOW_MS = 15 * 60_000;
+
+export function authRoutes({ config, modelFor, multiUser, passwordHash, source, store, version }) {
+  const loginFailures = new Map();
+
+  return [
+    { method: 'GET', path: /^\/api\/auth\/me$/, feature: null, handle: ({ res, auth }) => {
+      const cfg = config();
+      const signedIn = auth.userId !== undefined;
+      const model = signedIn ? modelFor(auth.user?.id, auth.role) : null;
+      return json(res, 200, {
+        authMode: cfg.authMode,
+        logoutUrl: cfg.logoutUrl || '',
+        isAdmin: Boolean(auth.isAdmin),
+        features: [...auth.features],
+        models: signedIn ? modelsFor(cfg, auth.role) : [],
+        model,
+        modelLabel: signedIn ? labelFor(cfg, model) : null,
+        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
+      });
+    } },
+
+    { method: 'POST', path: /^\/api\/auth\/login$/, feature: null, handle: async ({ req, res }) => {
+      const cfg = config();
+      if (cfg.authMode !== 'single') return json(res, 404, { error: 'not found' });
+      const who = req.socket.remoteAddress || '?';
+      const now = Date.now();
+      const f = loginFailures.get(who);
+      if (f && now - f.first > LOGIN_WINDOW_MS) loginFailures.delete(who);
+      const entry = loginFailures.get(who);
+      if (entry && entry.count >= LOGIN_MAX) {
+        return json(res, 429, { error: 'too many attempts, try again later' });
+      }
+      const { password } = await readJson(req);
+      if (!verifyPassword(password, passwordHash())) {
+        loginFailures.set(who, { first: entry?.first ?? now, count: (entry?.count ?? 0) + 1 });
+        audit('auth.rejected', { reason: 'bad_password' });
+        return json(res, 401, { error: 'wrong password' });
+      }
+      loginFailures.delete(who);
+      const token = createSession(store, OWNER_ID, cfg.sessionTtlDays);
+      audit('auth.login', { userId: OWNER_ID });
+      res.setHeader('set-cookie', sessionCookie(token, cfg.sessionSecret, { secure: isSecureRequest(req, cfg.trustedProxyCidrs) }));
+      return json(res, 200, { ok: true });
+    } },
+
+    { method: 'POST', path: /^\/api\/auth\/logout$/, feature: null, handle: ({ req, res }) => {
+      const cfg = config();
+      // The gateway owns the session; the client is sent to its logout page.
+      if (cfg.authMode === 'trusted-header') return json(res, 200, { redirect: cfg.logoutUrl || null });
+      if (cfg.authMode !== 'single') return json(res, 404, { error: 'not found' });
+      const token = sessionToken(req, cfg);
+      if (token) destroySession(store, token);
+      res.setHeader('set-cookie', clearCookie({ secure: isSecureRequest(req, cfg.trustedProxyCidrs) }));
+      return json(res, 200, { ok: true });
+    } },
+
+    // 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 }) => {
+      const cfg = config();
+      if (!multiUser()) return json(res, 400, { error: 'preferences are per-user; set the model in settings' });
+      const { model } = await readJson(req);
+      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' });
+      if (model && allowed !== '*' && !allowed.includes(model)) return json(res, 403, { error: 'that model is not available to you' });
+      store.users.setPref(auth.user.id, 'model', model ? model.trim() : null);
+      return json(res, 200, { model: modelFor(auth.user.id, auth.role) });
+    } },
+
+    // Non-secret facts about this deployment, for scripts verifying what is
+    // running: build, config hash, database schema, auth, MCP server names.
+    { method: 'GET', path: /^\/api\/meta$/, feature: null, handle: ({ res }) => json(res, 200, {
+      version: version,
+      schemaVersion: store.schemaVersion(),
+      fingerprint: fingerprint(config(), source.loadMcpServers()),
+      configMode: source.isFrozen() ? 'frozen' : 'editable',
+      authMode: config().authMode,
+      mcpServers: Object.keys(source.loadMcpServers()).sort()
+    }) }
+  ];
+}

package/src/routes/automations.js

@@ -0,0 +1,92 @@
+import { json, readJson } from '../http.js';
+import { validateSchedule } from '../automations/automation.js';
+import { FEATURE } from '../../public/shared/features.js';
+
+/** `newChatTitle` on an automation request: undefined when absent, false when
+ * present but unusable, otherwise the trimmed title. */
+function newChatTitleOf(body) {
+  if (body.newChatTitle === undefined || body.newChatTitle === null) return undefined;
+  const title = String(body.newChatTitle).trim();
+  return title && title.length <= 120 ? title : false;
+}
+
+const BAD_TITLE = { error: 'the new chat needs a name (at most 120 characters)' };
+
+export function automationRoutes({ scheduler, store }) {
+  const F = FEATURE.AUTOMATIONS;
+  return [
+    { method: 'GET', path: /^\/api\/automations$/, feature: F, handle: ({ res, auth }) =>
+      json(res, 200, { automations: store.automations.list(auth.userId), chats: store.chats.list(200, auth.userId) }) },
+
+    { method: 'POST', path: /^\/api\/automations$/, feature: F, handle: async ({ req, res, auth }) => {
+      const body = await readJson(req);
+      const newChatTitle = newChatTitleOf(body);
+      if (newChatTitle === false) return json(res, 400, BAD_TITLE);
+      let chat = newChatTitle ? null : store.chats.get(String(body.chatId || ''), auth.userId);
+      if (!newChatTitle && !chat) return json(res, 400, { error: 'a chat you own is required' });
+      const name = String(body.name || '').trim();
+      const prompt = String(body.prompt || '').trim();
+      if (!name || !prompt) return json(res, 400, { error: 'name and prompt are required' });
+      if (name.length > 120 || prompt.length > 12000) return json(res, 400, { error: 'name or prompt is too long' });
+      let schedule;
+      try { schedule = validateSchedule(body.cron, body.timezone); }
+      catch (err) { return json(res, 400, { error: err.message }); }
+      if (newChatTitle) chat = store.chats.create({ title: newChatTitle }, auth.userId);
+      const automation = store.automations.create({ ...schedule, chatId: chat.id, name, prompt, enabled: body.enabled !== false, source: 'user' }, auth.userId);
+      scheduler.arm();
+      return json(res, 201, { automation });
+    } },
+
+    { method: 'GET', path: /^\/api\/automations\/([\w.-]+)\/runs$/, feature: F, handle: ({ res, auth, params: [id] }) => {
+      const runs = store.automations.listRuns(id, auth.userId);
+      return runs ? json(res, 200, { runs }) : json(res, 404, { error: 'no such automation' });
+    } },
+
+    { method: 'POST', path: /^\/api\/automations\/([\w.-]+)\/trigger$/, feature: F, handle: async ({ res, auth, params: [id] }) => {
+      const automation = store.automations.get(id, auth.userId);
+      if (!automation) return json(res, 404, { error: 'no such automation' });
+      const run = await scheduler.trigger(automation, auth.userId);
+      return json(res, 202, { run });
+    } },
+
+    { method: 'PATCH', path: /^\/api\/automations\/([\w.-]+)$/, feature: F, handle: async ({ req, res, auth, params: [id] }) => {
+      const existing = store.automations.get(id, auth.userId);
+      if (!existing) return json(res, 404, { error: 'no such automation' });
+      const body = await readJson(req);
+      const patch = {};
+      for (const key of ['name', 'prompt', 'cron', 'timezone', 'enabled', 'chatId']) if (body[key] !== undefined) patch[key] = body[key];
+      const newChatTitle = newChatTitleOf(body);
+      if (newChatTitle === false) return json(res, 400, BAD_TITLE);
+      if (newChatTitle) delete patch.chatId;
+      if (patch.chatId !== undefined) {
+        const chat = store.chats.get(String(patch.chatId), auth.userId);
+        if (!chat) return json(res, 400, { error: 'a chat you own is required' });
+        patch.chatId = chat.id;
+      }
+      if (patch.name !== undefined) {
+        patch.name = String(patch.name).trim();
+        if (!patch.name || patch.name.length > 120) return json(res, 400, { error: 'name is required and must be at most 120 characters' });
+      }
+      if (patch.prompt !== undefined) {
+        patch.prompt = String(patch.prompt).trim();
+        if (!patch.prompt || patch.prompt.length > 12000) return json(res, 400, { error: 'prompt is required and must be at most 12000 characters' });
+      }
+      if (patch.cron !== undefined || patch.timezone !== undefined) {
+        let schedule;
+        try { schedule = validateSchedule(patch.cron ?? existing.cron, patch.timezone ?? existing.timezone); }
+        catch (err) { return json(res, 400, { error: err.message }); }
+        Object.assign(patch, schedule);
+      }
+      if (newChatTitle) patch.chatId = store.chats.create({ title: newChatTitle }, auth.userId).id;
+      const automation = store.automations.update(id, patch, auth.userId);
+      scheduler.arm();
+      return json(res, 200, { automation });
+    } },
+
+    { method: 'DELETE', path: /^\/api\/automations\/([\w.-]+)$/, feature: F, handle: ({ res, auth, params: [id] }) => {
+      if (!store.automations.delete(id, auth.userId)) return json(res, 404, { error: 'no such automation' });
+      scheduler.arm();
+      return json(res, 200, { ok: true });
+    } }
+  ];
+}

package/src/routes/chats.js

@@ -0,0 +1,232 @@
+import { json, readJson, TURN_LIMIT } from '../http.js';
+import { LockedError } from '../config/config.js';
+import { toView } from '../store/index.js';
+import { setOverride } from '../config/approval.js';
+import { actor } from '../access/auth_gate.js';
+import { normalizeUpload } from './documents.js';
+import { attachmentNote } from '../../public/shared/attachment_note.js';
+import { FEATURE } from '../../public/shared/features.js';
+
+const MAX_IMAGES = 8;
+const F = FEATURE.CHAT;
+
+/** Images and documents on a turn need their own features, whatever the route. */
+function refusedFeature(auth, { images, documentIds }) {
+  if (Array.isArray(images) && images.length && !auth.features.has(FEATURE.IMAGES)) return FEATURE.IMAGES;
+  if (Array.isArray(documentIds) && documentIds.length && !auth.features.has(FEATURE.ATTACHMENTS)) return FEATURE.ATTACHMENTS;
+  return null;
+}
+
+export function chatRoutes({ config, modelFor, runs, saveConfig, store, toolsFor }) {
+  const noChat = (res) => json(res, 404, { error: 'no such chat' });
+
+  return [
+    // `running` is what puts the dot in the sidebar: a turn belongs to the
+    // server, so a chat can be working while nothing is watching it.
+    { method: 'GET', path: /^\/api\/chats$/, feature: F, handle: ({ res, auth }) => json(res, 200, {
+      chats: store.chats.list(200, auth.userId).map((c) => ({ ...c, running: runs.isRunning(c.id) }))
+    }) },
+
+    { method: 'GET', path: /^\/api\/chats\/([\w.-]+)$/, feature: F, handle: ({ res, auth, params: [id] }) => {
+      const found = store.chats.get(id, auth.userId);
+      if (!found) return noChat(res);
+      const run = runs.get(found.id);
+      const live = run && !run.done;
+      const messages = store.messages.list(found.id).map(toView);
+      return json(res, 200, {
+        id: found.id,
+        title: found.title,
+        folder: found.folder || null,
+        epoch: found.epoch,
+        // A turn in flight has already written some of itself to the store.
+        // Cutting the transcript back to where the turn began lets the client
+        // replay the settled part and then play the run's events over the top,
+        // instead of rendering the same rounds twice.
+        messages: live ? messages.slice(0, run.baseCount) : messages,
+        running: Boolean(live),
+        queued: store.chats.listQueued(found.id),
+        tasks: store.chats.visibleTasks(found.id),
+        documents: store.documents.list(found.id)
+      });
+    } },
+
+    { method: 'DELETE', path: /^\/api\/chats\/([\w.-]+)$/, feature: F, handle: ({ res, auth, params: [id] }) => {
+      if (!store.chats.get(id, auth.userId)) return noChat(res);
+      store.chats.delete(id, auth.userId);
+      return json(res, 200, { ok: true });
+    } },
+
+    { method: 'GET', path: /^\/api\/chats\/([\w.-]+)\/stream$/, feature: F, handle: ({ res, auth, url, params: [id] }) => {
+      if (!store.chats.get(id, auth.userId)) return noChat(res);
+      const run = runs.get(id);
+      if (!run) return json(res, 404, { error: 'nothing running' });
+      return runs.attach(run, res, Number(url.searchParams.get('from')) || 0);
+    } },
+
+    // Rewriting a question and answering it again. Asking the same question
+    // again is the same operation with the same text, so there is one route.
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/edit$/, feature: F, handle: async ({ req, res, auth, params: [id] }) => {
+      const found = store.chats.get(id, auth.userId);
+      if (!found) return noChat(res);
+      // Rewriting history under a turn that is still reading it would leave
+      // the run answering a question that no longer exists.
+      if (runs.isRunning(id)) return json(res, 409, { error: 'that chat is still working; stop it first' });
+
+      const body = await readJson(req, TURN_LIMIT);
+      const { seq, message, documentIds, removeDocumentIds, images } = body;
+      const refused = refusedFeature(auth, body);
+      if (refused) return json(res, 403, { error: 'feature_disabled', feature: refused });
+      const text = String(message ?? '').trim();
+      if (!text) return json(res, 400, { error: 'message is required' });
+      const target = store.messages.list(id).find((m) => m.seq === Number(seq));
+      if (!target || target.role !== 'user') {
+        return json(res, 400, { error: 'seq must name a question of your own' });
+      }
+
+      store.chats.truncateFrom(id, Number(seq));
+      // A document is chat-scoped, not part of the message row that just got
+      // truncated, so dropping one during edit takes an explicit delete --
+      // this is the only place that happens. Nothing survives that would
+      // still reference it: truncateFrom already took every later message
+      // (the only other place a reference could live) with it.
+      for (const docId of Array.isArray(removeDocumentIds) ? removeDocumentIds : []) {
+        const doc = store.documents.get(docId, auth.userId);
+        if (doc?.chat_id === id) store.documents.delete(docId, auth.userId);
+      }
+      let content = text;
+      for (const docId of Array.isArray(documentIds) ? documentIds : []) {
+        const doc = store.documents.get(docId, auth.userId);
+        if (doc?.chat_id === id) content += attachmentNote(doc);
+      }
+      const kept = Array.isArray(images) ? images.filter((img) => img?.mime && img?.data) : [];
+      store.messages.add(id, { role: 'user', content, ...(kept.length ? { images: kept } : {}) });
+
+      // The run is started but not streamed back here. The client reloads the
+      // 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) });
+      return json(res, 200, { ok: true, running: true });
+    } },
+
+    // The user's answer to an approval prompt in the transcript.
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/approve$/, feature: F, handle: async ({ req, res, auth, params: [chatId] }) => {
+      if (!store.chats.get(chatId, auth.userId)) return noChat(res);
+      const { id, decision } = await readJson(req);
+      if (!['allow', 'always', 'deny'].includes(decision)) {
+        return json(res, 400, { error: 'decision must be allow, always or deny' });
+      }
+      const run = runs.get(chatId);
+      const pending = run?.approvals.get(id);
+      if (!pending) return json(res, 409, { error: 'that call is no longer waiting' });
+      run.approvals.delete(id);
+      // "Always" rewrites tool policy, which is the tools feature's to do;
+      // without it, the answer counts as allowing this one call.
+      if (decision === 'always' && auth.features.has(FEATURE.TOOLS)) {
+        // Approval lists set in code cannot be saved to; allow this call only.
+        try { saveConfig(setOverride(config(), pending.name, 'auto'), actor(auth)); }
+        catch (err) { if (!(err instanceof LockedError)) throw err; }
+      }
+      pending.resolve(decision);
+      return json(res, 200, { ok: true });
+    } },
+
+    // The user's answer to an ask_user question, or `skip` to let the run
+    // continue without one. Only the run's own open question can be
+    // answered; anything else (answered, timed out, stopped) is a 409.
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/answer$/, feature: F, handle: async ({ req, res, auth, params: [chatId] }) => {
+      if (!store.chats.get(chatId, auth.userId)) return noChat(res);
+      const { id, answer, skip } = await readJson(req, TURN_LIMIT);
+      const gone = () => json(res, 409, { error: 'that question is no longer waiting' });
+      const pending = runs.get(chatId)?.question;
+      if (!pending || pending.id !== id) return gone();
+      if (skip === true) return pending.settle('skipped') ? json(res, 200, { ok: true }) : gone();
+      const text = String(answer ?? '').trim();
+      if (!text) return json(res, 400, { error: 'answer is required' });
+      if (!pending.allowFreeText && !pending.choices.includes(text)) {
+        return json(res, 400, { error: 'answer must be one of the offered choices' });
+      }
+      return pending.settle('answered', text) ? json(res, 200, { ok: true }) : gone();
+    } },
+
+    // Input sent while a turn is running. Refused when nothing interactive
+    // is running (send it normally) and while an automation holds the chat.
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/queue$/, feature: F, handle: async ({ req, res, auth, params: [chatId] }) => {
+      if (!store.chats.get(chatId, auth.userId)) return noChat(res);
+      const { id, kind, message } = await readJson(req, TURN_LIMIT);
+      const text = String(message ?? '').trim();
+      if (!text) return json(res, 400, { error: 'message is required' });
+      if (!['steer', 'followup'].includes(kind)) return json(res, 400, { error: 'kind must be steer or followup' });
+      if (typeof id !== 'string' || !/^[\w.-]{1,64}$/.test(id)) return json(res, 400, { error: 'id is required' });
+      const run = runs.get(chatId);
+      if (!run || run.done) return json(res, 409, { error: 'nothing is running; send it as a message' });
+      if (run.unattended) return json(res, 409, { error: 'an automation is running in this chat; wait for it to finish' });
+      store.chats.addQueued(chatId, { id, kind, content: text });
+      runs.announceQueue(chatId);
+      return json(res, 200, { ok: true, items: store.chats.listQueued(chatId) });
+    } },
+
+    { method: 'DELETE', path: /^\/api\/chats\/([\w.-]+)\/queue\/([\w.-]+)$/, feature: F, handle: ({ res, auth, params: [chatId, itemId] }) => {
+      if (!store.chats.get(chatId, auth.userId)) return noChat(res);
+      const removed = store.chats.deleteQueued(chatId, itemId);
+      runs.announceQueue(chatId);
+      return json(res, removed ? 200 : 409, removed ? { ok: true } : { error: 'already delivered' });
+    } },
+
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/stop$/, feature: F, handle: ({ res, auth, params: [chatId] }) => {
+      if (!store.chats.get(chatId, auth.userId)) return noChat(res);
+      runs.get(chatId)?.ac.abort();
+      return json(res, 200, { ok: true });
+    } },
+
+    { method: 'POST', path: /^\/api\/chat$/, feature: F, handle: async ({ req, res, auth }) => {
+      const body = await readJson(req, TURN_LIMIT);
+      const { chatId, message, documentIds, images } = body;
+      const refused = refusedFeature(auth, body);
+      if (refused) return json(res, 403, { error: 'feature_disabled', feature: refused });
+      if (!config().apiKey) return json(res, 400, { error: 'No API key. Set TINYWEBUI_API_KEY or apiKey in the config file.' });
+      if (!message) return json(res, 400, { error: 'message is required' });
+
+      // The client no longer ships the transcript: it sends the new turn and
+      // the server replays what it already holds. That is what stops a
+      // page-sized tool result from crossing the wire on every message.
+      const owned = chatId && store.chats.get(chatId, auth.userId);
+      // Someone else's id is "no such chat", never a primary-key clash.
+      if (chatId && !owned && store.chats.byId(chatId)) return noChat(res);
+      const chat = owned || store.chats.create({ id: chatId, title: String(message).slice(0, 60) }, auth.userId);
+
+      // Attachments are surfaced as plain text inline notes rather than a
+      // system-prompt change, the same idiom compact.js uses for a compacted
+      // artifact -- the model sees "[Attached document: ...]" in the message
+      // it's already reading and knows to call read_document on the id.
+      let content = String(message);
+      for (const id of Array.isArray(documentIds) ? documentIds : []) {
+        const doc = store.documents.get(id, auth.userId);
+        if (!doc || doc.chat_id !== chat.id) continue;
+        content += attachmentNote(doc);
+      }
+
+      // Images ride directly on the message as OpenAI multimodal content
+      // parts -- unlike a document there is no text to extract, so the bytes
+      // have to go up with the turn that attached them. Usually already
+      // normalized client-side (/api/images/normalize); normalizing again is a
+      // cheap passthrough then, and a safety net for callers that skipped it.
+      const imgs = [];
+      for (const img of Array.isArray(images) ? images.slice(0, MAX_IMAGES) : []) {
+        const normalized = await normalizeUpload(img?.mime, img?.dataBase64);
+        if (normalized) imgs.push(normalized);
+      }
+
+      store.messages.add(chat.id, { role: 'user', content, ...(imgs.length ? { images: imgs } : {}) });
+
+      // The turn is started, not awaited. Closing the tab detaches a
+      // listener; it no longer kills the work, and the answer is in the store
+      // whether or not anyone was watching when it landed.
+      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) });
+      return runs.attach(run, res, 0);
+    } }
+  ];
+}

package/src/routes/documents.js

@@ -0,0 +1,133 @@
+import { json, readJson, UPLOAD_LIMIT } from '../http.js';
+import { extractText, servingFor } from '../files/documents.js';
+import { normalizeImage } from '../files/images.js';
+import { logger } from '../log.js';
+import { FEATURE } from '../../public/shared/features.js';
+import { CORPUS } from '../store/index.js';
+
+const log = logger('retrieval');
+
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+
+/** Decodes and normalizes one uploaded image; null on anything unusable. */
+export async function normalizeUpload(mimeRaw, dataBase64) {
+  const mime = String(mimeRaw || '');
+  if (!mime.startsWith('image/') && mime !== '') return null;
+  let buf;
+  try { buf = Buffer.from(String(dataBase64 || ''), 'base64'); } catch { return null; }
+  if (!buf.length || buf.length > MAX_FILE_BYTES) return null;
+  try {
+    const normalized = await normalizeImage(buf, mime);
+    return normalized && { mime: normalized.mime, data: normalized.data.toString('base64') };
+  } catch {
+    return null;
+  }
+}
+
+export function documentRoutes({ retrieval, store }) {
+  // Uploads and attaches land before the first message exists, so the chat is
+  // created lazily, the same way /api/chat does for a brand-new conversation.
+  // Null when the id is someone else's: "no such chat", never a key clash.
+  const chatFor = (chatId, auth, title) => {
+    const own = store.chats.get(chatId, auth.userId);
+    if (own) return own;
+    if (store.chats.byId(chatId)) return null;
+    return store.chats.create({ id: chatId, title: String(title).slice(0, 60) }, auth.userId);
+  };
+  // Embedded once, in the background; a question that arrives first waits for it.
+  const ingest = (doc) => retrieval.ingest(CORPUS.DOCUMENTS, doc.id)
+    .catch((err) => log.error(`embedding ${doc.id} failed: ${err.message}`));
+
+  return [
+    // Uploads, including the paste-as-file path.
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/documents$/, feature: FEATURE.ATTACHMENTS, handle: async ({ req, res, auth, params: [chatId] }) => {
+      const { filename, mime, dataBase64 } = await readJson(req, UPLOAD_LIMIT);
+      if (!filename || typeof dataBase64 !== 'string') {
+        return json(res, 400, { error: 'filename and dataBase64 are required' });
+      }
+      let buf;
+      try {
+        buf = Buffer.from(dataBase64, 'base64');
+      } catch {
+        return json(res, 400, { error: 'dataBase64 is not valid base64' });
+      }
+      if (buf.length > MAX_FILE_BYTES) {
+        return json(res, 400, { error: `file exceeds ${MAX_FILE_BYTES.toLocaleString('en-US')} byte limit` });
+      }
+
+      let text;
+      try {
+        text = await extractText(buf, String(filename));
+      } catch (err) {
+        return json(res, 400, { error: err.message });
+      }
+      if (!text.trim()) return json(res, 400, { error: 'no extractable text in that file' });
+
+      const chat = chatFor(chatId, auth, filename);
+      if (!chat) return json(res, 404, { error: 'no such chat' });
+      // The same file dropped in twice is one document in the chat.
+      const already = store.documents.findInChat(chat.id, buf);
+      if (already) return json(res, 200, { chatId: chat.id, document: already });
+      const doc = store.documents.add(chat.id, { filename: String(filename), mime: mime || null, content: text, original: buf }, retrieval.passageSettings());
+      ingest(doc);
+      return json(res, 200, { chatId: chat.id, document: doc });
+    } },
+
+    // What the user has attached in earlier chats, one line per distinct file,
+    // for the "attach from earlier chats" picker.
+    { method: 'GET', path: /^\/api\/documents$/, feature: FEATURE.ATTACHMENTS, handle: ({ res, auth }) => {
+      return json(res, 200, { documents: store.documents.library(auth.userId) });
+    } },
+
+    // Attaches a file the user already uploaded elsewhere, without uploading
+    // it again: the chat gets its own copy of the text (same stored file).
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/documents\/attach$/, feature: FEATURE.ATTACHMENTS, handle: async ({ req, res, auth, params: [chatId] }) => {
+      const { documentId } = await readJson(req);
+      if (typeof documentId !== 'string' || !documentId) return json(res, 400, { error: 'documentId is required' });
+      // Checked before the chat is created, so a bad id leaves no empty chat behind.
+      const source = store.documents.get(documentId, auth.userId);
+      if (!source) return json(res, 404, { error: 'no such document' });
+      const chat = chatFor(chatId, auth, source.filename);
+      if (!chat) return json(res, 404, { error: 'no such chat' });
+      const doc = store.documents.copyToChat(documentId, chat.id, auth.userId, retrieval.passageSettings());
+      if (!doc.existing) ingest(doc);
+      return json(res, 200, { chatId: chat.id, document: doc });
+    } },
+
+    // Lets the "files" rail open a document's full extracted text -- the
+    // same content the model reads via read_document, in a plain new tab.
+    // Documents have no delete route of their own: the only way one goes
+    // away is editing the message that attached it (see /edit in chats.js).
+    { method: 'GET', path: /^\/api\/documents\/([\w.-]+)$/, feature: FEATURE.ATTACHMENTS, handle: ({ res, auth, params: [id] }) => {
+      const doc = store.documents.get(id, auth.userId);
+      if (!doc) return json(res, 404, { error: 'no such document' });
+      return json(res, 200, { filename: doc.filename, mime: doc.mime, content: doc.content });
+    } },
+
+    // What the "artifacts" rail opens: the file as uploaded. Documents stored
+    // before originals were kept fall back to their extracted text.
+    { method: 'GET', path: /^\/api\/documents\/([\w.-]+)\/original$/, feature: FEATURE.ATTACHMENTS, handle: ({ res, auth, params: [id] }) => {
+      const doc = store.documents.get(id, auth.userId);
+      if (!doc) return json(res, 404, { error: 'no such document' });
+      const original = store.documents.original(id, auth.userId);
+      const { type, inline } = original ? servingFor(doc.filename) : servingFor('.txt');
+      const body = original || Buffer.from(doc.content, 'utf8');
+      // The name is percent-encoded (RFC 5987) so it cannot break out of the header.
+      const disposition = `${inline ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(doc.filename)}`;
+      res.writeHead(200, { 'content-type': type, 'content-length': body.length, 'content-disposition': disposition });
+      res.end(body);
+    } },
+
+    // Converts one staged image to a wire-safe format before it's ever sent,
+    // so the composer's own preview and the optimistic thumbnail in the
+    // transcript show the same bytes the model (and the store) end up with,
+    // instead of a HEIC/AVIF the browser can't decode until the turn ends
+    // and the chat reloads with what the server stored.
+    { method: 'POST', path: /^\/api\/images\/normalize$/, feature: FEATURE.IMAGES, handle: async ({ req, res }) => {
+      const { mime, dataBase64 } = await readJson(req, UPLOAD_LIMIT);
+      const normalized = await normalizeUpload(mime, dataBase64);
+      if (!normalized) return json(res, 400, { error: 'unrecognized or oversized image' });
+      return json(res, 200, normalized);
+    } }
+  ];
+}

package/src/routes/library.js

@@ -0,0 +1,51 @@
+import { json, readJson } from '../http.js';
+import { FEATURE } from '../../public/shared/features.js';
+
+/** The sidebar's search, usage statistics, and folders. */
+export function libraryRoutes({ runs, store }) {
+  return [
+    // Full-text search across every stored message, for the sidebar's search
+    // box. GET with a query string, so it is bookmarkable and cacheable like
+    // any other read.
+    { method: 'GET', path: /^\/api\/search$/, feature: FEATURE.SEARCH, handle: ({ res, auth, url }) => {
+      const q = url.searchParams.get('q') || '';
+      const limit = 30;
+      // A chat mid-turn is still being written -- store.search would be
+      // matching against text that has not settled, and openChat/rejoin is
+      // not built to land a click in the middle of a live stream. Overfetch
+      // and filter rather than ask the store to know about runs, which is a
+      // server-only concept it has no business importing.
+      const results = store.search.chats(q, limit * 2, auth.userId)
+        .filter((r) => !runs.isRunning(r.chatId))
+        .slice(0, limit);
+      return json(res, 200, { results });
+    } },
+
+    // ?model= narrows every figure to one model; adding &provider= to one
+    // upstream serving it.
+    { method: 'GET', path: /^\/api\/usage$/, feature: FEATURE.STATISTICS, handle: ({ res, auth, url }) => {
+      const q = url.searchParams;
+      const filter = { model: q.get('model') || undefined, provider: q.has('provider') ? q.get('provider') : undefined };
+      return json(res, 200, { days: store.usage.rollup(auth.userId, filter), statistics: store.usage.statistics(auth.userId, filter) });
+    } },
+
+    { method: 'GET', path: /^\/api\/folders$/, feature: FEATURE.FOLDERS, handle: ({ res, auth }) =>
+      json(res, 200, { folders: store.chats.listFolders(auth.userId) }) },
+
+    { method: 'POST', path: /^\/api\/folders$/, feature: FEATURE.FOLDERS, handle: async ({ req, res, auth }) => {
+      const { name } = await readJson(req);
+      const created = store.chats.createFolder(name, auth.userId);
+      if (!created) return json(res, 400, { error: 'folder name required' });
+      return json(res, 200, { folder: created });
+    } },
+
+    { method: 'POST', path: /^\/api\/chats\/([\w.-]+)\/organize$/, feature: FEATURE.FOLDERS, handle: async ({ req, res, auth, params: [chatId] }) => {
+      const { folder, tags } = await readJson(req);
+      const found = store.chats.get(chatId, auth.userId);
+      if (!found) return json(res, 404, { error: 'no such chat' });
+      if (folder) store.chats.createFolder(folder, auth.userId);
+      const updated = store.chats.organize(chatId, { folder, tags }, auth.userId);
+      return json(res, 200, { folder: updated.folder });
+    } }
+  ];
+}