@sleep2agi/commhub-server 0.9.0-preview.144 → 0.9.0-preview.146

package/src/user-avatar-image.ts

@@ -0,0 +1,153 @@
+// #725-adjacent? No: Hub 专用账号头像上传（通信Mac马 交付单）。
+//
+// 头像不是普通附件：它必须 PNG、边长 ≤512、≤8 MiB，且只能由本人用自己的
+// **用户令牌**写入；读取按「人类资料可见性」（本人或共享网络的合法成员）判定，
+// 不借用 /api/files 的附件 ACL（那是按网络/会话/DM 作用域判的，语义不同）。
+//
+// 这个模块只做纯校验，便于单测与复用；HTTP 与落库在 server.ts。
+import { inflateSync } from "node:zlib";
+
+// 校验强度：结构（签名/chunk/CRC）+ 真实解码（IDAT 解压且扫描行长度与 IHDR 相符）。
+
+export const MAX_AVATAR_BYTES = 8 * 1024 * 1024;
+/** 客户端会把图重编码到最长边 512；服务端独立复核这条上限。 */
+export const MAX_AVATAR_EDGE = 512;
+/** version 只允许 URL 安全字符，长度有界（避免拼路径时引入 `.`、`/`）。 */
+export const AVATAR_VERSION_RE = /^[A-Za-z0-9_-]{1,128}$/;
+export const AVATAR_FIELD = "file";
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+export type AvatarImageCheck =
+  | { ok: true; width: number; height: number }
+  | { ok: false; reason: "empty" | "too_large" | "not_png" | "truncated" | "bad_dimensions" | "too_big" | "bad_crc" | "bad_image" | "interlaced_unsupported" };
+
+const CHANNELS: Record<number, number> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+
+/** 标准 CRC-32（PNG 每个 chunk 的尾部）。表只建一次。 */
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function be32(bytes: Uint8Array, offset: number): number {
+  return ((bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]) >>> 0;
+}
+
+/**
+ * PNG 结构校验：签名 + 逐个 chunk 的 CRC + 必须有 IDAT 且以 IEND 结尾。
+ *
+ * 只信任「结构完整」而不是「声明了什么」：截断的 33/40 字节、零填充的伪图
+ * （IHDR 对但 CRC 与 IDAT 缺失）都会被拒；合法用户因此不能把已有头像
+ * 覆盖成一张显示不出来的图。
+ */
+export function inspectAvatarImage(input: Uint8Array): AvatarImageCheck {
+  if (input.byteLength === 0) return { ok: false, reason: "empty" };
+  if (input.byteLength > MAX_AVATAR_BYTES) return { ok: false, reason: "too_large" };
+  for (let i = 0; i < PNG_SIGNATURE.length && i < input.byteLength; i++) {
+    if (input[i] !== PNG_SIGNATURE[i]) return { ok: false, reason: "not_png" };
+  }
+  if (input.byteLength < 45) return { ok: false, reason: "truncated" }; // 签名 + IHDR(25) + 最小 IEND(12)
+
+  let pos = 8;
+  let width = 0;
+  let height = 0;
+  let sawIHDR = false;
+  let idatChunks = 0;
+  let sawIEND = false;
+  let sawPLTE = false;
+  let bitDepth = 0;
+  let colorType = 0;
+  const idat: Uint8Array[] = [];
+
+  while (pos + 12 <= input.byteLength) {
+    const length = be32(input, pos);
+    const type = String.fromCharCode(input[pos + 4], input[pos + 5], input[pos + 6], input[pos + 7]);
+    const dataStart = pos + 8;
+    const dataEnd = dataStart + length;
+    const crcEnd = dataEnd + 4;
+    if (crcEnd > input.byteLength) return { ok: false, reason: "truncated" };
+    if (!sawIHDR && type !== "IHDR") return { ok: false, reason: "not_png" };
+    if ((crc32(input.subarray(pos + 4, dataEnd)) >>> 0) !== be32(input, dataEnd)) {
+      return { ok: false, reason: "bad_crc" };
+    }
+    if (type === "IHDR") {
+      if (sawIHDR || length !== 13) return { ok: false, reason: "not_png" };
+      width = be32(input, dataStart);
+      height = be32(input, dataStart + 4);
+      bitDepth = input[dataStart + 8];
+      colorType = input[dataStart + 9];
+      const compression = input[dataStart + 10];
+      const filter = input[dataStart + 11];
+      const interlace = input[dataStart + 12];
+      // 只接受规范的 IHDR 取值组合；非法组合的图多数解码器也会拒绝。
+      const legalDepth: Record<number, number[]> = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+      if (!legalDepth[colorType]?.includes(bitDepth)) return { ok: false, reason: "not_png" };
+      if (compression !== 0 || filter !== 0) return { ok: false, reason: "not_png" };
+      // 本实现只校验逐行（interlace=0）扫描布局：Adam7(=1) 的布局不同，其余取值(2..255)
+      // 在 PNG 规范里根本不合法。一律明确拒收，而不是错算长度后放行。
+      if (interlace !== 0) return { ok: false, reason: "interlaced_unsupported" };
+      if (width === 0 || height === 0) return { ok: false, reason: "bad_dimensions" };
+      if (width > MAX_AVATAR_EDGE || height > MAX_AVATAR_EDGE) return { ok: false, reason: "too_big" };
+      sawIHDR = true;
+    } else if (type === "PLTE") {
+      if (length === 0 || length % 3 !== 0) return { ok: false, reason: "not_png" };
+      sawPLTE = true;
+    } else if (type === "IDAT") {
+      idatChunks++;
+      idat.push(input.subarray(dataStart, dataEnd));
+    } else if (type === "IEND") {
+      if (length !== 0) return { ok: false, reason: "not_png" };
+      if (crcEnd !== input.byteLength) return { ok: false, reason: "not_png" };
+      sawIEND = true;
+      break;
+    }
+    pos = crcEnd;
+  }
+
+  if (!sawIHDR || !sawIEND) return { ok: false, reason: "truncated" };
+  if (idatChunks === 0) return { ok: false, reason: "not_png" };
+  // 调色板图必须带 PLTE，否则解码器无从取色。
+  if (colorType === 3 && !sawPLTE) return { ok: false, reason: "not_png" };
+  // CRC 只证明「容器没坏」，不证明 IDAT 里是图像数据：真解一次 zlib，并核对
+  // 解压后长度正好等于 IHDR 声明的扫描行总长（每行 1 字节 filter + 像素字节）。
+  const bytesPerRow = Math.ceil((width * (CHANNELS[colorType] ?? 0) * bitDepth) / 8);
+  const expected = height * (1 + bytesPerRow);
+  let raw: Uint8Array;
+  try {
+    const merged = Buffer.concat(idat.map(part => Buffer.from(part)));
+    raw = new Uint8Array(inflateSync(merged, { maxOutputLength: expected + 1024 }));
+  } catch {
+    return { ok: false, reason: "bad_image" };
+  }
+  if (raw.byteLength !== expected) return { ok: false, reason: "bad_image" };
+  for (let row = 0; row < height; row++) {
+    if (raw[row * (1 + bytesPerRow)] > 4) return { ok: false, reason: "bad_image" }; // 过滤器 0..4
+  }
+  return { ok: true, width, height };
+}
+
+export function isValidAvatarVersion(value: unknown): value is string {
+  return typeof value === "string" && AVATAR_VERSION_RE.test(value);
+}
+
+export function avatarUrl(userId: string, version: string): string {
+  return `/api/users/${encodeURIComponent(userId)}/avatar/${version}.png`;
+}
+
+/** 只接受 multipart 里的单张图；多余字段一律拒绝，避免「顺手塞个 filename 覆盖路径」。 */
+export function isMultipart(contentType: string | null): boolean {
+  return !!contentType && /^multipart\/form-data\b/i.test(contentType);
+}

package/src/user-avatar-upload-http.test.ts

@@ -0,0 +1,294 @@
+import { expect, test } from "bun:test";
+import { register, createNetworkTokenForNode, addNetworkMember } from "./auth.js";
+import { db } from "./db.js";
+import { inspectAvatarImage, MAX_AVATAR_BYTES } from "./user-avatar-image.js";
+import { deflateSync } from "node:zlib";
+
+// 1×1 PNG（透明）。只用来走真实 multipart → 真实文件头校验。
+const PNG_1X1 = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+  "base64",
+);
+/** 真的 8-bit RGBA PNG：IHDR + 一段 zlib 压缩的扫描行 + IEND，CRC 全对。 */
+function realPng(width: number, height: number): Buffer {
+  const crcTable = new Uint32Array(256).map((_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+  });
+  const crc = (buf: Buffer) => {
+    let c = 0xffffffff;
+    for (const byte of buf) c = crcTable[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const chunk = (type: string, data: Buffer) => {
+    const len = Buffer.alloc(4); len.writeUInt32BE(data.length);
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const sum = Buffer.alloc(4); sum.writeUInt32BE(crc(body));
+    return Buffer.concat([len, body, sum]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0; // 8-bit RGBA
+  const raw = Buffer.alloc((1 + width * 4) * height); // 每行前面一个 filter 字节 0
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw)),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+
+/** CRC 全对、但 IDAT 内容非法的 PNG：用来证明「结构通过 ≠ 图像有效」。 */
+function pngWithIdat(idat: Buffer, opts: { colorType?: number; bitDepth?: number; width?: number; height?: number; interlace?: number } = {}): Buffer {
+  const crcTable = new Uint32Array(256).map((_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+  });
+  const crc = (buf: Buffer) => {
+    let c = 0xffffffff;
+    for (const byte of buf) c = crcTable[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const chunk = (type: string, data: Buffer) => {
+    const len = Buffer.alloc(4); len.writeUInt32BE(data.length);
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const sum = Buffer.alloc(4); sum.writeUInt32BE(crc(body));
+    return Buffer.concat([len, body, sum]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(opts.width ?? 1, 0); ihdr.writeUInt32BE(opts.height ?? 1, 4);
+  ihdr[8] = opts.bitDepth ?? 8; ihdr[9] = opts.colorType ?? 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = opts.interlace ?? 0;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr), chunk("IDAT", idat), chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+test("account avatar upload: user token only, PNG limits, visibility by shared network, revoke, atomic replace", async () => {
+  const a = register("avup_alice", "AvatarUpload1!");
+  const b = register("avup_bob", "AvatarUpload1!");
+  const outsider = register("avup_outsider", "AvatarUpload1!");
+  expect(a.ok && b.ok && outsider.ok).toBe(true);
+  expect(addNetworkMember(a.network_id!, b.user!.user_id, "member").ok).toBe(true);
+  const node = createNetworkTokenForNode(a.user!.user_id, a.network_id!, "avup_alice", "avup_node");
+  expect(node.ok).toBe(true);
+
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+
+  const upload = async (token: string | null, bytes: Buffer, fieldName = "file", extra?: [string, string]) => {
+    const form = new FormData();
+    form.append(fieldName, new Blob([new Uint8Array(bytes)], { type: "image/png" }), "a.png");
+    if (extra) form.append(extra[0], extra[1]);
+    const headers: Record<string, string> = {};
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(`${base}/api/auth/me/avatar/upload`, { method: "POST", headers, body: form });
+    const body = await res.json().catch(() => null);
+    return { status: res.status, body: body as any };
+  };
+  const getAvatar = async (token: string | null, path: string) => {
+    const res = await fetch(base + path, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
+    return { status: res.status, headers: res.headers, bytes: new Uint8Array(await res.arrayBuffer()) };
+  };
+
+  try {
+    // 前置：陌生人之间没有共享网络。
+    expect(db.get("SELECT 1 AS ok FROM network_members m WHERE m.user_id=?1 AND m.network_id=?2", outsider.user!.user_id, a.network_id!)).toBeNull();
+
+    // 匿名/节点令牌都不是「本人」。
+    expect((await upload(null, PNG_1X1)).status).toBe(401);
+    expect((await upload(node.token!, PNG_1X1)).status).toBe(403);
+
+    // 畸形输入：非 PNG、超边长、空、多字段、非 multipart。
+    expect((await upload(a.token!, Buffer.from("not a png"))).body.error).toBe("invalid_image");
+    expect((await upload(a.token!, realPng(600, 600))).body.reason).toBe("too_big");
+    expect((await upload(a.token!, Buffer.alloc(0))).status).toBe(400);
+    expect((await upload(a.token!, PNG_1X1, "other")).status).toBe(400);
+    expect((await upload(a.token!, PNG_1X1, "file", ["avatar_url", "/etc/passwd"])).status).toBe(400);
+    const notMultipart = await fetch(`${base}/api/auth/me/avatar/upload`, {
+      method: "POST", headers: { Authorization: `Bearer ${a.token}`, "Content-Type": "application/json" }, body: "{}",
+    });
+    expect(notMultipart.status).toBe(415);
+
+    // 成功：URL 由 Hub 发，version 只含 URL 安全字符。
+    const ok1 = await upload(a.token!, PNG_1X1);
+    expect(ok1.status).toBe(200);
+    expect(ok1.body.ok).toBe(true);
+    expect(ok1.body.user_id).toBe(a.user!.user_id);
+    expect(ok1.body.avatar_url).toMatch(new RegExp(`^/api/users/${a.user!.user_id}/avatar/[A-Za-z0-9_-]{1,128}\\.png$`));
+
+    // 资料读取面必须同步看到这张头像（同一事务写 users.avatar_url）。
+    const meAfter = await fetch(`${base}/api/auth/me`, { headers: { Authorization: `Bearer ${a.token}` } });
+    const meBody = await meAfter.json() as any;
+    expect(meBody.user.avatar_url).toBe(ok1.body.avatar_url);
+
+    const first = await getAvatar(a.token!, ok1.body.avatar_url);
+    expect(first.status).toBe(200);
+    expect(first.headers.get("content-type")).toBe("image/png");
+    expect(first.headers.get("cache-control")).toBe("private, no-store");
+    expect(first.headers.get("location")).toBeNull();
+    expect(first.bytes.byteLength).toBe(PNG_1X1.byteLength);
+
+    // 同网络成员可读；不同网络的人读不到（与不存在同码，避免探测）。
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(200);
+    expect((await getAvatar(outsider.token!, ok1.body.avatar_url)).status).toBe(404);
+    expect((await getAvatar(null, ok1.body.avatar_url)).status).toBe(401);
+    expect((await getAvatar(node.token!, ok1.body.avatar_url)).status).toBe(403);
+    expect((await getAvatar(a.token!, `/api/users/${a.user!.user_id}/avatar/nope..%2F.png`)).status).toBe(404);
+
+    // 撤权后立刻读不到。
+    expect(db.run("DELETE FROM network_members WHERE user_id=?1 AND network_id=?2", [b.user!.user_id, a.network_id!]).changes).toBeGreaterThan(0);
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(404);
+
+    // 「CRC 正确但图像数据非法」也必须 400：结构通过不等于可解码。
+    const beforeInvalid = db.get<{ version: string; bytes: number }>(
+      "SELECT version, bytes FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id);
+    expect((await upload(a.token!, pngWithIdat(Buffer.alloc(0)))).body.reason).toBe("bad_image");
+    expect((await upload(a.token!, pngWithIdat(Buffer.from("not-a-zlib-stream")))).body.reason).toBe("bad_image");
+    // 解压成功但扫描行长度不符（声明 2×2 RGBA，实际只给 1×1）
+    expect((await upload(a.token!, pngWithIdat(deflateSync(Buffer.alloc(5)), { width: 2, height: 2 }))).body.reason).toBe("bad_image");
+    const afterInvalid = db.get<{ version: string; bytes: number }>(
+      "SELECT version, bytes FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id);
+    expect(afterInvalid).toEqual(beforeInvalid);
+
+    // P2：清空后旧托管 URL 立即失效（本人与同网络成员都不能再读到）。
+    const putProfile = async (token: string, avatar_url: string | null) => {
+      const res = await fetch(`${base}/api/auth/me/avatar`, {
+        method: "PUT", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ avatar_url }),
+      });
+      return { status: res.status, body: await res.json() as any };
+    };
+    // 重新造一张可读的：此刻 b 已被撤权，先用 outsider 之外的同网成员做读校验
+    expect(addNetworkMember(a.network_id!, b.user!.user_id, "member").ok).toBe(true);
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(200);
+    expect((await putProfile(a.token!, null)).status).toBe(200);
+    expect((await getAvatar(a.token!, ok1.body.avatar_url)).status).toBe(404);
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(404);
+    const meCleared = await fetch(`${base}/api/auth/me`, { headers: { Authorization: `Bearer ${a.token}` } });
+    expect(((await meCleared.json()) as any).user.avatar_url).toBeNull();
+    expect(db.get("SELECT 1 AS ok FROM user_avatar_uploads WHERE user_id=?1", [a.user!.user_id])).toBeNull();
+
+    // 换成池里的一张（非托管 URL）也必须撤销旧托管行。
+    const again = await upload(a.token!, PNG_1X1);
+    expect(again.status).toBe(200);
+    expect((await getAvatar(a.token!, again.body.avatar_url)).status).toBe(200);
+    expect((await putProfile(a.token!, "/avatars/avatar-03.webp")).status).toBe(200);
+    expect((await getAvatar(a.token!, again.body.avatar_url)).status).toBe(404);
+    expect(db.get("SELECT 1 AS ok FROM user_avatar_uploads WHERE user_id=?1", [a.user!.user_id])).toBeNull();
+
+    // 原子替换：一次失败的上传不能把上一张弄丢；成功后旧 version 立刻 404。
+    const baseline = await upload(a.token!, PNG_1X1);
+    expect(baseline.status).toBe(200);
+    const beforeBad = db.get<{ version: string }>("SELECT version FROM user_avatar_uploads WHERE user_id=?1", [a.user!.user_id]);
+    expect(beforeBad?.version).toBeTruthy();
+    expect((await upload(a.token!, Buffer.from("broken"))).status).toBe(400);
+    expect(db.get<{ version: string }>("SELECT version FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id)!.version).toBe(beforeBad!.version);
+    expect((await getAvatar(a.token!, baseline.body.avatar_url)).status).toBe(200);
+
+    const ok2 = await upload(a.token!, realPng(512, 512));
+    expect(ok2.status).toBe(200);
+    expect(ok2.body.avatar_url).not.toBe(baseline.body.avatar_url);
+    expect((await getAvatar(a.token!, baseline.body.avatar_url)).status).toBe(404);
+    expect((await getAvatar(a.token!, ok2.body.avatar_url)).status).toBe(200);
+    expect(db.get<{ width: number }>("SELECT width FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id)!.width).toBe(512);
+  } finally {
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id IN (?1, ?2, ?3)", [a.user!.user_id, b.user!.user_id, outsider.user!.user_id]);
+    await hub.stop?.();
+  }
+});
+
+test("deleted network leaves only ghost membership: member loses read, owner keeps it", async () => {
+  const owner = register("avup_netowner", "AvatarUpload1!");
+  const member = register("avup_netmember", "AvatarUpload1!");
+  expect(owner.ok && member.ok).toBe(true);
+  expect(addNetworkMember(owner.network_id!, member.user!.user_id, "member").ok).toBe(true);
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+  const read = async (token: string, path: string) => (await fetch(base + path, { headers: { Authorization: `Bearer ${token}` } })).status;
+  try {
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(PNG_1X1)], { type: "image/png" }), "a.png");
+    const up = await fetch(`${base}/api/auth/me/avatar/upload`, { method: "POST", headers: { Authorization: `Bearer ${owner.token}` }, body: form });
+    expect(up.status).toBe(200);
+    const url = ((await up.json()) as any).avatar_url as string;
+    expect(await read(member.token!, url)).toBe(200);
+    // 只删网络行，故意留下 network_members 残行：live membership 必须据此拒绝。
+    db.run("DELETE FROM networks WHERE network_id = ?1", [owner.network_id!]);
+    expect(await read(member.token!, url)).toBe(404);
+    expect(await read(owner.token!, url)).toBe(200); // 本人不依赖成员关系
+  } finally {
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id = ?1", [owner.user!.user_id]);
+    db.run("UPDATE users SET avatar_url = NULL WHERE user_id = ?1", [owner.user!.user_id]);
+    await hub.stop?.();
+  }
+});
+
+test("upload is rate limited before multipart parsing, and rejects keepalive leftovers", async () => {
+  const u = register("avup_ratelimit", "AvatarUpload1!");
+  expect(u.ok).toBe(true);
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+  const send = async (body: BodyInit | null, contentType?: string) => {
+    const headers: Record<string, string> = { Authorization: `Bearer ${u.token}` };
+    if (contentType) headers["Content-Type"] = contentType;
+    const res = await fetch(`${base}/api/auth/me/avatar/upload`, { method: "POST", headers, body });
+    return { status: res.status, connection: res.headers.get("connection"), body: await res.json().catch(() => null) as any };
+  };
+  const multipart = () => {
+    const form = new FormData();
+    form.append("file", new Blob([PNG_1X1], { type: "image/png" }), "a.png");
+    return form;
+  };
+  try {
+    // 60 次成功用满这一小时的桶（每张 1×1，成本可忽略）。
+    for (let i = 0; i < 60; i++) {
+      const r = await send(multipart());
+      expect(r.status).toBe(200);
+    }
+    const limited = await send(multipart());
+    expect(limited.status).toBe(429);
+    expect(limited.body.error).toBe("rate_limited");
+    expect(limited.connection).toBe("close");
+    // 关键：限流在 multipart 解析之前——普通 JSON 也被先拒成 429，而不是 415。
+    const early = await send("{}", "application/json");
+    expect(early.status).toBe(429);
+    expect(early.connection).toBe("close");
+  } finally {
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id = ?1", [u.user!.user_id]);
+    db.run("UPDATE users SET avatar_url = NULL WHERE user_id = ?1", [u.user!.user_id]);
+    await hub.stop?.();
+  }
+});
+
+test("image inspector: signature, shape and size limits", () => {
+  expect(inspectAvatarImage(PNG_1X1)).toEqual({ ok: true, width: 1, height: 1 });
+  expect(inspectAvatarImage(new Uint8Array(0))).toEqual({ ok: false, reason: "empty" });
+  expect(inspectAvatarImage(new Uint8Array(10))).toEqual({ ok: false, reason: "not_png" });
+  expect(inspectAvatarImage(Buffer.from(realPng(16, 16).subarray(0, 20)))).toEqual({ ok: false, reason: "truncated" });
+  expect(inspectAvatarImage(Buffer.from(realPng(16, 16).subarray(0, 40)))).toEqual({ ok: false, reason: "truncated" });
+  const truePng = realPng(16, 16);
+  const corrupt = Buffer.from(truePng); corrupt[corrupt.length - 20] ^= 0xff;
+  expect(inspectAvatarImage(corrupt).ok).toBe(false);
+  expect(inspectAvatarImage(realPng(513, 16))).toEqual({ ok: false, reason: "too_big" });
+  // Adam7 隔行：明确拒收（不按非隔行长度错算）
+  const interlaced = pngWithIdat(deflateSync(Buffer.alloc(6)), { width: 1, height: 1, interlace: 1 });
+  expect(inspectAvatarImage(interlaced)).toEqual({ ok: false, reason: "interlaced_unsupported" });
+  // 规范外取值 2..255：同样拒收（负控：扫描数据本来是非隔行的合法布局，
+  // 只有 interlace 字节非法，证明拦截来自 interlace 判断而不是解码失败）
+  for (const bad of [2, 3, 128, 255]) {
+    const invalidInterlace = pngWithIdat(deflateSync(Buffer.alloc(6)), { width: 1, height: 1, interlace: bad });
+    expect(inspectAvatarImage(invalidInterlace)).toEqual({ ok: false, reason: "interlaced_unsupported" });
+  }
+  const zeroWide = realPng(0, 1); // 宽 0 + 正确 CRC：专证 bad_dimensions 而不是 bad_crc
+  expect(inspectAvatarImage(zeroWide)).toEqual({ ok: false, reason: "bad_dimensions" });
+  const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0xe0, ...new Array(40).fill(0)]);
+  expect(inspectAvatarImage(jpeg)).toEqual({ ok: false, reason: "not_png" });
+  expect(inspectAvatarImage(Buffer.alloc(MAX_AVATAR_BYTES + 1))).toEqual({ ok: false, reason: "too_large" });
+});