dscord 0.2.0-alpha.1 → 0.4.0-alpha.3

package/central/avatars.md

@@ -0,0 +1,74 @@
+# 自定义头像
+
+用户可以修改自己的头像，以及自己名下 Bot 的头像。头像属于中央账号资料，使用稳定的中央账号 ID；Bot 不需要在线，修改头像不改变 Bot 的运行配置版本、不重启节点或 Session。
+
+## 使用
+
+- 自己：左下角账号菜单 → 个人设置 → 账号。自己的成员资料卡也提供更换入口。
+- Bot：Bot 主页 → 设置，或“我的 Bot”展开对应 Bot 的设置。所属 Bot 的成员资料卡也能修改。
+- 选择 JPG、PNG 或静态 WebP，拖动、缩放并预览，点击“保存头像”。手机支持拖动和双指缩放，键盘可操作缩放及水平/垂直位置滑块。
+- “恢复默认”恢复名字首字占位。占位颜色由稳定身份决定。
+- 上传失败保留原头像与裁剪预览。另一台设备先保存时显示冲突，读取最新版本并保留预览；再次保存表示用户选择覆盖该版本。
+
+头像在账号入口、成员卡、消息、私聊与 Bot 导航、身份组和 `@` 候选中展示。消息展示当前头像，已有聊天正文不重写。Bot 标识与运行状态仍独立展示。中英文、明暗主题使用现有设置。
+
+## 存储与配置
+
+中央的 `central.sqlite` 中增加独立的 `account_profiles` 表，保存头像资源 ID、资料版本和更新时间。标准化后的图片默认位于中央数据目录下的 `avatars/<资源ID>/{64,128,512}.webp`。直接运行默认使用 `.local/central/`，可用已有 `DSCORD_CENTRAL_DATA_DIR` 指定数据目录。Compose 使用现有 `central-data` 卷中的 `/central/avatars/`，无需新增卷。
+
+在中央的 `central-config.json` 中可增加以下字段；省略时采用这些默认值。修改后重启中央服务：
+
+```json
+{
+  "avatars": {
+    "backend": "local",
+    "directory": "avatars",
+    "maxUploadBytes": 5242880,
+    "sizes": [64, 128, 512]
+  }
+}
+```
+
+`directory` 可用绝对路径，或相对于中央数据目录的路径；使用外部目录时自行挂载持久卷。`maxUploadBytes` 范围为 1 至 20971520；反向代理的请求体限制应至少覆盖该值。三个基础尺寸必须保留，可增加 32–1024 之间的尺寸，最多六个。
+
+本期后端为 `local`。现有 `DS_GROUP_S3_*` 配置用于 Synapse 的聊天附件与头像副本，不会改变中央头像的存储位置。中央的 S3 后端尚未实现。
+
+备份中央时，除现有数据库和签名密钥外，同时备份头像目录；备份聊天服务器时继续覆盖其 Core 与 Synapse 数据。标准化的历史头像保留，避免破坏已有链接与 Matrix 历史引用，本期没有自动回收历史版本。原始上传图不持久保存，处理临时目录在请求结束时清除。
+
+中央仅增加身份图片存储；聊天消息和任务附件继续由聊天服务器保存。
+
+## 同步与图片处理
+
+Core 每 5 秒按中央账号 ID 批量核对资料版本。读取到更新后保存到本地账号库，并使用该账号的服务凭据将图片同步至本服 Synapse，设置对应的 Matrix `avatar_url`。图片上传成功但资料写入失败时保留 Matrix 媒体回执，后续重试复用该回执。Core 重启后从持久记录继续同步。中央或 Matrix 暂不可用不阻断聊天 API；恢复后继续补齐。
+
+头像保存后，当前页面及同源标签页立即更新；其他设备和服务器通过版本轮询更新。无网络时不能保存，无法加载图片时显示占位。跨服务器同步是最终一致的，不要求所有服务器同时在线。
+
+头像资料版本独立于 Bot 设置的 `revision`。中央写入采用版本检查，先完成图片持久化再更新引用；失败或旧版本不会改写当前头像。
+
+服务端使用固定依赖 `sharp@0.35.5`，校验真实图片格式、静态帧、40MP 像素上限与裁剪边界，校正 EXIF 方向，重新编码 WebP 并去除原元数据。安装时保留 npm 的 optional dependencies，Linux amd64/arm64 使用对应平台的预编译 sharp/libvips 包；继续支持 `npm ci --ignore-scripts`。
+
+头像图片是公开身份资源，通过无账号令牌的内容版本地址访问，可由浏览器缓存。编辑接口只接受本人或 Bot 所属人的中央会话，聊天服务器管理员身份不授予全局头像编辑权。
+
+## 接口
+
+| 中央接口 | 作用 |
+| --- | --- |
+| `GET /api/me/avatar` | 读取本人头像、版本及上传上限 |
+| `PUT /api/me/avatar?version=N&left=X&top=Y&size=S` | 上传原图字节，按校正方向后的像素裁剪；裁剪参数可全部省略，使用居中裁剪 |
+| `DELETE /api/me/avatar?version=N` | 恢复默认 |
+| `GET/PUT/DELETE /api/bots/:id/avatar` | 所属人修改对应 Bot，参数同上 |
+| `GET /api/profiles?ids=...` | 读取至多 100 个已知中央账号 ID 或全局 ID 的公开头像版本 |
+| `GET /avatars/:assetId/:size.webp` | 读取标准化图片 |
+
+写入缺少版本返回 400，版本冲突返回 409；格式不支持返回 415，超限返回 413。客户端调用中央时使用既有 `clientOrigins` 跨域配置。
+
+## 验证
+
+```sh
+npm run check
+npm run build
+node --test --test-concurrency=1 tests/*.browser.mjs
+node tests/avatars.runtime.mjs
+```
+
+`avatars.test.mjs` 覆盖真实中央 HTTP、图片解码、权限、失败保留、并发更新、持久化和带 Matrix 替身的同步重试。`avatars.browser.mjs` 使用真实中央 HTTP 与 Chromium 验证裁剪、保存、跨标签、冲突、离线 Bot、手机布局及双语。`avatars.runtime.mjs` 显式启动两套隔离 Synapse/Core，验证自动同步、真实 Matrix 媒体、中央/Core 重启及恢复默认；使用合成账号，模型调用为 0。运行日志和截图位于忽略的 `.local/avatar-validation/`，运行脚本会移除本次创建的容器。

package/central/avatars.mjs

@@ -0,0 +1,105 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import sharp from 'sharp';
+
+const failure = (status, code) => Object.assign(new Error(code), { status, code });
+const ASSET = /^[a-f0-9]{64}$/;
+export function avatarOptions(input = {}) {
+  const result = { backend: 'local', directory: 'avatars', maxUploadBytes: 5 * 1024 * 1024, sizes: [64, 128, 512], ...input };
+  if (result.backend !== 'local') throw new Error('avatars.backend currently supports local storage');
+  if (typeof result.directory !== 'string' || !result.directory.trim()) throw new Error('avatars.directory is required');
+  if (!Number.isSafeInteger(result.maxUploadBytes) || result.maxUploadBytes < 1 || result.maxUploadBytes > 20 * 1024 * 1024) throw new Error('avatars.maxUploadBytes must be between 1 and 20971520');
+  if (!Array.isArray(result.sizes) || ![64, 128, 512].every(size => result.sizes.includes(size)) || result.sizes.length > 6 || result.sizes.some(size => !Number.isSafeInteger(size) || size < 32 || size > 1024)) throw new Error('avatars.sizes must include 64, 128 and 512, with at most six sizes between 32 and 1024');
+  result.sizes = [...new Set(result.sizes)].sort((a, b) => a - b);
+  return result;
+}
+
+/** Identity images only. Original uploads and processing directories are never published. */
+export class Avatars {
+  constructor({ store, dataRoot, issuer, config }) {
+    Object.assign(this, { store, issuer });
+    this.options = avatarOptions(config);
+    this.directory = path.resolve(dataRoot, this.options.directory);
+    store.db.exec(`CREATE TABLE IF NOT EXISTS account_profiles (
+      account_id TEXT PRIMARY KEY REFERENCES accounts(id), version INTEGER NOT NULL,
+      asset_id TEXT, updated_at INTEGER NOT NULL);`);
+    store.profileOf = account => this.profile(account);
+  }
+  profile(account) {
+    const row = this.store.db.prepare('SELECT * FROM account_profiles WHERE account_id=?').get(account.id);
+    return { id: account.id, globalId: this.store.globalId(account.username), profileVersion: row?.version ?? 0,
+      avatar: row?.asset_id ? { id: row.asset_id, url: `${this.issuer}/avatars/${row.asset_id}/128.webp`,
+        sizes: Object.fromEntries(this.options.sizes.map(size => [size, `${this.issuer}/avatars/${row.asset_id}/${size}.webp`])) } : null };
+  }
+  expected(account, value) {
+    if (value === null || !/^\d+$/.test(value)) throw failure(400, 'AVATAR_VERSION_REQUIRED');
+    const version = Number(value);
+    if (!Number.isSafeInteger(version) || this.profile(account).profileVersion !== version) throw failure(409, 'AVATAR_CHANGED');
+    return version;
+  }
+  commit(account, version, assetId) {
+    this.store.db.exec('BEGIN IMMEDIATE');
+    try {
+      this.expected(account, String(version));
+      if (this.store.account(account.id)?.status !== 'active') throw failure(403, 'ACCOUNT_INACTIVE');
+      this.store.db.prepare(`INSERT INTO account_profiles VALUES (?,?,?,?) ON CONFLICT(account_id) DO UPDATE SET
+        version=excluded.version,asset_id=excluded.asset_id,updated_at=excluded.updated_at`).run(account.id, version + 1, assetId, this.store.now());
+      this.store.db.exec('COMMIT');
+    } catch (error) { this.store.db.exec('ROLLBACK'); throw error; }
+    return this.profile(account);
+  }
+  async upload(request, query) {
+    const type = String(request.headers['content-type'] || '').split(';')[0];
+    if (!['image/jpeg', 'image/png', 'image/webp'].includes(type)) throw failure(415, 'AVATAR_FORMAT');
+    if (Number(request.headers['content-length']) > this.options.maxUploadBytes) throw failure(413, 'AVATAR_TOO_LARGE');
+    let size = 0;
+    const chunks = [];
+    // Do not destroy the socket on a bounded-body rejection; let HTTP return the error.
+    for await (const chunk of request.iterator({ destroyOnReturn: false })) {
+      size += chunk.length;
+      if (size > this.options.maxUploadBytes) { request.resume(); throw failure(413, 'AVATAR_TOO_LARGE'); }
+      chunks.push(chunk);
+    }
+    let bytes;
+    try {
+      const image = sharp(Buffer.concat(chunks), { limitInputPixels: 40_000_000, failOn: 'warning' });
+      const meta = await image.metadata();
+      if (!['jpeg', 'png', 'webp'].includes(meta.format) || (meta.pages ?? 1) !== 1) throw failure(415, 'AVATAR_FORMAT');
+      const swapped = [5, 6, 7, 8].includes(meta.orientation);
+      const width = swapped ? meta.height : meta.width, height = swapped ? meta.width : meta.height;
+      const cropKeys = ['left', 'top', 'size'];
+      const hasCrop = cropKeys.some(key => query.has(key));
+      let pipeline = image.autoOrient();
+      if (hasCrop) {
+        const [left, top, edge] = cropKeys.map(key => query.has(key) ? Number(query.get(key)) : NaN);
+        if (![left, top, edge].every(Number.isSafeInteger) || left < 0 || top < 0 || edge < 1 || left + edge > width || top + edge > height) throw failure(400, 'AVATAR_CROP');
+        pipeline = pipeline.extract({ left, top, width: edge, height: edge });
+      }
+      bytes = await pipeline.resize(512, 512, { fit: 'cover' }).webp({ quality: 85 }).toBuffer();
+    } catch (error) { if (error.status) throw error; throw failure(400, 'AVATAR_INVALID_IMAGE'); }
+    const id = createHash('sha256').update(bytes).digest('hex');
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const temp = path.join(this.directory, `.upload-${randomUUID()}`);
+    await mkdir(temp, { mode: 0o700 });
+    try {
+      for (const edge of this.options.sizes) {
+        const output = edge === 512 ? bytes : await sharp(bytes).resize(edge, edge).webp({ quality: 85 }).toBuffer();
+        await writeFile(path.join(temp, `${edge}.webp`), output, { mode: 0o600 });
+      }
+      try { await rename(temp, path.join(this.directory, id)); }
+      catch (error) { if (!['ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
+    } finally { await rm(temp, { recursive: true, force: true }); }
+    return id;
+  }
+  async serve(response, id, size) {
+    if (!ASSET.test(id) || !this.options.sizes.includes(Number(size))) throw failure(404, 'AVATAR_NOT_FOUND');
+    let bytes;
+    try { bytes = await readFile(path.join(this.directory, id, `${size}.webp`)); }
+    catch (error) { if (error.code === 'ENOENT') throw failure(404, 'AVATAR_NOT_FOUND'); throw error; }
+    response.writeHead(200, { 'Content-Type': 'image/webp', 'Content-Length': bytes.length,
+      'Cache-Control': 'public, max-age=86400, immutable', 'X-Content-Type-Options': 'nosniff',
+      'Access-Control-Allow-Origin': '*', 'Cross-Origin-Resource-Policy': 'cross-origin' });
+    response.end(bytes);
+  }
+}

package/central/directory.mjs

@@ -0,0 +1,224 @@
+import { randomInt } from 'node:crypto';
+import { failure } from './store.mjs';
+
+export const SERVER_WELL_KNOWN = '/.well-known/dscord/server';
+/** A server whose public page has not been read for this long drops out of search until it is read again. */
+export const LISTING_STALE_MS = 3 * 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_BODY_BYTES = 64 * 1024;
+const MAX_RESULTS = 50;
+/** How a server can be found: by keyword search, only by its exact number, or not at all. */
+export const DISCOVERY = ['public', 'number', 'hidden'];
+/** How people join: anyone with a central account, or only with an invitation from the server. */
+export const JOIN = ['open', 'invite'];
+/** Where a listing stands with this central's administrators. Only listed servers are searchable. */
+export const LISTING_STATUS = ['pending', 'listed', 'rejected', 'banned'];
+/** Whether a newly submitted server waits for an administrator ('review') or is listed at once ('open'). */
+export const LISTING_MODES = ['review', 'open'];
+// Server numbers are eight digits, handed out at random so they say nothing about when a server was listed.
+const NUMBER_MIN = 10_000_000;
+const NUMBER_SPAN = 90_000_000;
+
+const iso = value => value === null || value === undefined ? null : new Date(value).toISOString();
+
+function text(value, max, field) {
+  if (value === undefined || value === null) return '';
+  if (typeof value !== 'string' || value.length > max || /[\u0000-\u0008\u000b-\u001f\u007f]/.test(value)) throw failure(502, 'SERVER_PAGE_INVALID', `${field} is not valid`);
+  return value.trim();
+}
+
+function count(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+/** The public page a chat server serves at /.well-known/dscord/server, reduced to what the index keeps. */
+export function readServerPage(value, origin) {
+  if (!value || typeof value !== 'object' || value.schemaVersion !== 1) throw failure(502, 'SERVER_PAGE_INVALID', 'Unknown server page version');
+  if (value.origin !== origin) throw failure(502, 'SERVER_PAGE_INVALID', 'The page names a different origin');
+  const tags = Array.isArray(value.tags) ? value.tags : [];
+  if (tags.length > 10) throw failure(502, 'SERVER_PAGE_INVALID', 'At most 10 tags');
+  return {
+    central: typeof value.central === 'string' ? value.central : '',
+    discovery: DISCOVERY.includes(value.discovery) ? value.discovery : 'hidden',
+    page: {
+      name: text(value.name, 80, 'name') || new URL(origin).hostname,
+      description: text(value.description, 500, 'description'),
+      tags: [...new Set(tags.map(tag => text(tag, 32, 'tag').toLowerCase()).filter(Boolean))],
+      members: { people: count(value.members?.people), bots: count(value.members?.bots) },
+      join: JOIN.includes(value.join) ? value.join : 'invite',
+    },
+  };
+}
+
+async function readJson(response) {
+  const reader = response.body?.getReader();
+  if (!reader) return response.json();
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_BODY_BYTES) { await reader.cancel(); throw failure(502, 'SERVER_PAGE_INVALID', 'The server page is too large'); }
+    chunks.push(value);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+/**
+ * The server index. A chat server submits its origin; the index reads the server's public page from that origin and
+ * keeps reading it. A page served at the origin and naming this central is the server's consent to be listed, so
+ * submitting needs no account. This central's administrators decide what is listed: new servers wait for review
+ * unless the central lists them at once.
+ */
+export class ServerDirectory {
+  constructor({ db, issuer, now = Date.now, fetch = globalThis.fetch, fetchVia = {} }) {
+    Object.assign(this, { db, issuer, now, fetch, fetchVia });
+    db.exec(`CREATE TABLE IF NOT EXISTS servers (origin TEXT PRIMARY KEY, number INTEGER NOT NULL UNIQUE,
+        status TEXT NOT NULL CHECK(status IN ('pending','listed','rejected','banned')), note TEXT NOT NULL DEFAULT '',
+        discovery TEXT NOT NULL, page_json TEXT NOT NULL, submitted_at INTEGER NOT NULL, reviewed_at INTEGER,
+        fetched_at INTEGER, last_error TEXT, checked_at INTEGER NOT NULL);`);
+  }
+
+  async read(origin) {
+    const base = this.fetchVia[origin] || origin;
+    let response;
+    try {
+      response = await this.fetch(`${base}${SERVER_WELL_KNOWN}`, { headers: { Accept: 'application/json' }, redirect: 'error',
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    } catch { throw failure(502, 'SERVER_UNREACHABLE', 'Could not reach the server page'); }
+    if (response.status === 404) throw failure(409, 'SERVER_PAGE_MISSING', 'The server does not publish a directory page');
+    if (!response.ok) throw failure(502, 'SERVER_UNREACHABLE', `The server page answered ${response.status}`);
+    let body;
+    try { body = await readJson(response); } catch (error) { throw error.code ? error : failure(502, 'SERVER_PAGE_INVALID', 'The server page is not JSON'); }
+    const page = readServerPage(body, origin);
+    if (page.central !== this.issuer) throw failure(409, 'CENTRAL_MISMATCH', 'The server trusts a different central');
+    return page;
+  }
+
+  /**
+   * Reads the page and keeps the server. A new server is pending under review and listed at once otherwise;
+   * a rejected server that submits again goes back to pending. A banned origin stays out.
+   */
+  async submit(origin, { review = true } = {}) {
+    const existing = this.server(origin);
+    if (existing?.status === 'banned') throw failure(403, 'SERVER_BANNED', 'This central does not list the server');
+    const read = await this.read(origin);
+    const at = this.now();
+    const page = JSON.stringify(read.page);
+    if (existing) {
+      const status = existing.status === 'rejected' ? 'pending' : existing.status;
+      this.db.prepare(`UPDATE servers SET status=?, discovery=?, page_json=?, submitted_at=CASE WHEN ?<>status THEN ? ELSE submitted_at END,
+          fetched_at=?, last_error=NULL, checked_at=? WHERE origin=?`).run(status, read.discovery, page, status, at, at, at, origin);
+    } else {
+      // A server keeps its number for as long as it stays in the index.
+      for (;;) {
+        const number = NUMBER_MIN + randomInt(NUMBER_SPAN);
+        try {
+          this.db.prepare(`INSERT INTO servers(origin,number,status,discovery,page_json,submitted_at,reviewed_at,fetched_at,checked_at)
+              VALUES (?,?,?,?,?,?,?,?,?)`).run(origin, number, review ? 'pending' : 'listed', read.discovery, page, at, review ? null : at, at, at);
+          break;
+        } catch (error) { if (!String(error.message).includes('UNIQUE')) throw error; }
+      }
+    }
+    return this.submittedView(this.server(origin));
+  }
+
+  server(origin) { return this.db.prepare('SELECT * FROM servers WHERE origin=?').get(origin); }
+
+  existing(origin) {
+    const row = this.server(origin);
+    if (!row) throw failure(404, 'SERVER_NOT_FOUND');
+    return row;
+  }
+
+  /** Reads the page again. A page that cannot be read keeps the last listing, which drops out of search once stale. */
+  async refresh(origin) {
+    const row = this.server(origin);
+    if (!row) return undefined;
+    const at = this.now();
+    try {
+      const read = await this.read(origin);
+      this.db.prepare('UPDATE servers SET discovery=?, page_json=?, fetched_at=?, last_error=NULL, checked_at=? WHERE origin=?')
+        .run(read.discovery, JSON.stringify(read.page), at, at, origin);
+    } catch (error) {
+      if (!error.code) throw error;
+      this.db.prepare('UPDATE servers SET last_error=?, checked_at=? WHERE origin=?').run(error.code, at, origin);
+    }
+    return this.server(origin);
+  }
+
+  async refreshAll() {
+    for (const { origin } of this.db.prepare("SELECT origin FROM servers WHERE status IN ('pending','listed') ORDER BY checked_at").all()) {
+      await this.refresh(origin);
+    }
+  }
+
+  /** An administrator's decision: list, reject or ban a server, with an optional note the server's operators can read. */
+  decide(origin, status, note = '') {
+    if (!['listed', 'rejected', 'banned'].includes(status)) throw failure(400, 'LISTING_STATUS_INVALID');
+    if (typeof note !== 'string' || note.length > 500) throw failure(400, 'NOTE_INVALID');
+    this.existing(origin);
+    this.db.prepare('UPDATE servers SET status=?, note=?, reviewed_at=? WHERE origin=?').run(status, note.trim(), this.now(), origin);
+    return this.adminView(this.server(origin));
+  }
+
+  /** Drops a server from the index, number and all; a removed server may submit again and gets a new number. */
+  remove(origin) {
+    if (!this.db.prepare('DELETE FROM servers WHERE origin=?').run(origin).changes) throw failure(404, 'SERVER_NOT_FOUND');
+  }
+
+  /** What a submitting server learns: its number and where its listing stands. */
+  submittedView(row) {
+    return { origin: row.origin, number: row.number, status: row.status, note: row.note, discovery: row.discovery };
+  }
+
+  adminView(row) {
+    return { ...this.submittedView(row), ...JSON.parse(row.page_json), submittedAt: iso(row.submitted_at), reviewedAt: iso(row.reviewed_at),
+      fetchedAt: iso(row.fetched_at), checkedAt: iso(row.checked_at), lastError: row.last_error };
+  }
+
+  /** Every server in the index for its administrators, newest submissions first, optionally of one status. */
+  list({ status = '' } = {}) {
+    if (status && !LISTING_STATUS.includes(status)) throw failure(400, 'LISTING_STATUS_INVALID');
+    const rows = status ? this.db.prepare('SELECT * FROM servers WHERE status=? ORDER BY submitted_at DESC').all(status)
+      : this.db.prepare('SELECT * FROM servers ORDER BY submitted_at DESC').all();
+    return rows.map(row => this.adminView(row));
+  }
+
+  counts() {
+    return Object.fromEntries(LISTING_STATUS.map(status => [status,
+      this.db.prepare('SELECT COUNT(*) AS n FROM servers WHERE status=?').get(status).n]));
+  }
+
+  /**
+   * Listed servers read within the last three days. A query of digits finds the server with that number, unless it is hidden;
+   * otherwise only public servers are searched, and every word must appear in the name, description or tags.
+   */
+  search({ q = '', tag = '', limit = 20 } = {}) {
+    const query = String(q).trim();
+    const fresh = this.now() - LISTING_STALE_MS;
+    if (/^\d{8}$/.test(query)) {
+      const row = this.db.prepare("SELECT * FROM servers WHERE number=? AND status='listed' AND discovery IN ('public','number') AND fetched_at>=?")
+        .get(Number(query), fresh);
+      if (row) return [this.publicView(row, JSON.parse(row.page_json))];
+    }
+    const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const wanted = String(tag).trim().toLowerCase();
+    const size = Math.min(Math.max(Number.parseInt(limit, 10) || 20, 1), MAX_RESULTS);
+    return this.db.prepare("SELECT * FROM servers WHERE status='listed' AND discovery='public' AND fetched_at>=?").all(fresh)
+      .map(row => ({ row, page: JSON.parse(row.page_json) }))
+      .filter(({ page }) => {
+        if (wanted && !page.tags.includes(wanted)) return false;
+        const haystack = [page.name, page.description, ...page.tags].join('\n').toLowerCase();
+        return words.every(word => haystack.includes(word));
+      })
+      .sort((a, b) => b.page.members.people - a.page.members.people || a.page.name.localeCompare(b.page.name))
+      .slice(0, size)
+      .map(({ row, page }) => this.publicView(row, page));
+  }
+
+  publicView(row, page) {
+    return { origin: row.origin, number: row.number, ...page, updatedAt: iso(row.fetched_at) };
+  }
+}

package/central/rules.mjs

@@ -0,0 +1,51 @@
+// The central server owns the account format. Chat servers and clients read the
+// published rule; they never define their own.
+
+// A username becomes the Matrix localpart on every chat server, so a central rule
+// can only narrow the characters Matrix allows in a localpart.
+export const MATRIX_LOCALPART = /^[a-z0-9._=\-/]+$/;
+const MAX_LOCALPART = 64;
+
+export const DEFAULT_USERNAME_RULE = Object.freeze({
+  pattern: '^[a-z][a-z0-9._-]*$',
+  minLength: 3,
+  maxLength: 32,
+  reserved: Object.freeze(['admin', 'root', 'system', 'dscord', 'central']),
+});
+
+function fail(message) {
+  throw new Error(`usernameRule: ${message}`);
+}
+
+/** The rule from central configuration, checked once at start. */
+export function usernameRule(input = {}) {
+  const rule = { ...DEFAULT_USERNAME_RULE, ...input };
+  if (typeof rule.pattern !== 'string' || !rule.pattern.startsWith('^') || !rule.pattern.endsWith('$')) fail('pattern must be anchored with ^ and $');
+  let expression;
+  try { expression = new RegExp(rule.pattern, 'u'); }
+  catch (error) { fail(`pattern does not compile: ${error.message}`); }
+  if (!Number.isSafeInteger(rule.minLength) || rule.minLength < 1) fail('minLength must be a positive integer');
+  if (!Number.isSafeInteger(rule.maxLength) || rule.maxLength < rule.minLength || rule.maxLength > MAX_LOCALPART) {
+    fail(`maxLength must be between minLength and ${MAX_LOCALPART}`);
+  }
+  if (!Array.isArray(rule.reserved) || rule.reserved.some(name => typeof name !== 'string')) fail('reserved must be a list of names');
+  const reserved = [...new Set(rule.reserved.map(name => name.toLowerCase()))].sort();
+  return Object.freeze({
+    pattern: rule.pattern, minLength: rule.minLength, maxLength: rule.maxLength, reserved: Object.freeze(reserved),
+    /** The stored (lowercase) username, or a reason it is refused. */
+    check(value) {
+      if (typeof value !== 'string') return { error: 'USERNAME_REQUIRED' };
+      const name = value.trim().toLowerCase();
+      if (name.length < rule.minLength || name.length > rule.maxLength) return { error: 'USERNAME_LENGTH' };
+      if (!MATRIX_LOCALPART.test(name) || !expression.test(name)) return { error: 'USERNAME_CHARACTERS' };
+      if (reserved.includes(name)) return { error: 'USERNAME_RESERVED' };
+      return { username: name };
+    },
+  });
+}
+
+/** What chat servers and clients see. */
+export function publicRule(rule) {
+  return { pattern: rule.pattern, minLength: rule.minLength, maxLength: rule.maxLength, reserved: [...rule.reserved],
+    charset: MATRIX_LOCALPART.source, caseInsensitive: true, immutable: true };
+}