@cosmicdrift/kumiko-framework 0.316.0 → 0.317.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.316.0",
+  "version": "0.317.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.316.0",
-    "@cosmicdrift/kumiko-types": "0.316.0",
+    "@cosmicdrift/kumiko-http": "0.317.0",
+    "@cosmicdrift/kumiko-types": "0.317.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.316.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.317.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/query.ts

@@ -1237,3 +1237,21 @@ export async function deleteManyBatched(
 export async function transaction<T>(db: AnyDb, fn: (tx: BunDbRunner) => Promise<T>): Promise<T> {
   return (await asRawClient(db).begin(async (tx) => fn(tx as BunDbRunner))) as T;
 }
+
+// A tx/savepoint handle has no begin(); fail closed instead of nesting silently or TypeError-ing.
+export async function runInNewTransaction<T>(
+  db: unknown,
+  fn: (tx: DbRunner) => Promise<T>,
+): Promise<T> {
+  const raw = asRawClient(db) as unknown as {
+    begin?: <TResult>(cb: (tx: unknown) => Promise<TResult>) => Promise<TResult>;
+  };
+  if (typeof raw.begin !== "function") {
+    throw new InternalError({
+      message:
+        "runInNewTransaction: runner has no begin() — already inside a transaction or savepoint.",
+    });
+  }
+  // @cast-boundary driver tx handle → DbRunner at the single seam
+  return raw.begin((tx) => fn(tx as DbRunner));
+}

package/src/changes.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.317.0",
+    "type": "fix",
+    "title": "Changeset block parser keeps blank lines inside a multiline field",
+    "detail": "A blank line inside a `detail:`/`migration:` `|` block ended the\ncontinuation early because the check only looked for a leading two-space\nindent. The next indented line then no longer matched `key: value` on its\nown and parseChangesetChanges threw \"invalid kumiko-changes line\" instead\nof the real cause. Blank lines inside the block are now kept as paragraph\nbreaks in the field value."
+  },
+  {
+    "version": "0.317.0",
+    "type": "breaking",
+    "title": "\"files: a valid upload (png/jpeg/gif/webp/pdf/doc/docx) under the wrong extension is normalized to its real type instead of rejected, when that type is in the field's accept list or the upload has no accept restriction at all\"",
+    "detail": "A real PNG or WebP saved with a .jpg extension (a common case for renamed\nscreenshots or messenger downloads) was rejected with content_mismatch\neven when the field's accept explicitly allows png/webp, or when the upload\nis unattached and has no accept restriction at all. validateFileContent now\nalso accepts the field's accept list; when the sniffed byte signature\ndoesn't match the declared extension but the sniffed type's own extension is\nin accept, the upload proceeds under the sniffed mimeType with a storage key\nbuilt from the corrected extension, and the response reports the corrected\nmimeType. When there is no accept restriction at all, any recognized\nsignature (png, jpeg, gif, webp, pdf, doc, docx) normalizes the same way.\nThe original filename is kept as the display name. A sniffed type whose\nextension is not in a non-empty accept is still rejected with\ncontent_mismatch.",
+    "migration": "validateFileContent's signature changes from (fileName: string, content: Uint8Array): string | null to (fileName: string, content: Uint8Array, accept?: readonly string[]): FileContentValidationResult ({kind:\"ok\"} | {kind:\"normalized\", extension, mimeType} | {kind:\"rejected\", error}). A direct caller that checked \"if (result)\" for an error must switch to checking result.kind === \"rejected\" and reading result.error — every branch of the new return type is a truthy object, so an unmigrated truthy check would now reject every upload. No caller besides the built-in POST /api/files route calls this function directly today (checked across kumiko-framework, kumiko-enterprise, kumiko-platform, kumiko-studio and every app consumer). buildStorageKey gains an optional trailing extensionOverride parameter; existing calls without it are unaffected."
+  },
+  {
+    "version": "0.317.0",
+    "type": "improvement",
+    "title": "runInOwnTransaction(tenantDb, fn) runs fn in a fresh transaction on a TenantDb's pool runner",
+    "detail": "Exported from @cosmicdrift/kumiko-framework/db. fn receives a TenantDb with the same tenant, mode and grants bound to the new transaction. Fails closed for a TenantDb not built by createTenantDb, a memberReadOnly TenantDb, and a runner that is already inside a transaction."
+  },
   {
     "version": "0.316.0",
     "type": "fix",

package/src/db/__tests__/run-in-own-transaction.integration.test.ts

@@ -0,0 +1,166 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { createBooleanField, createEntity, createTextField } from "../../engine";
+import { AccessDeniedError, InternalError } from "../../errors";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import type { TableColumns } from "../dialect";
+import { buildEntityTable } from "../table-builder";
+import {
+  assertPersonalDataWrite,
+  createTenantDb,
+  type PersonalDataGate,
+  runInOwnTransaction,
+} from "../tenant-db";
+
+const entity = createEntity({
+  table: "run_in_own_tx_items",
+  fields: {
+    name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    isActive: createBooleanField({ default: true }),
+  },
+  softDelete: true,
+});
+
+const table: TableColumns = buildEntityTable("runInOwnTxItem", entity);
+
+let testDb: TestDb;
+const tenant1 = TestUsers.admin; // tenantId: 1
+const tenant2 = TestUsers.otherTenant; // tenantId: 2
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, entity, "runInOwnTxItem");
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("runInOwnTransaction", () => {
+  test("the tenant filter holds on the tx-bound db", async () => {
+    const tdb1 = createTenantDb(testDb.db, tenant1.tenantId);
+    const tdb2 = createTenantDb(testDb.db, tenant2.tenantId);
+    const marker = `shared-name-${crypto.randomUUID()}`;
+    await tdb2.insertOne(table, { name: marker });
+
+    const rows = await runInOwnTransaction(tdb1, async (txDb) => {
+      await txDb.insertOne(table, { name: marker });
+      return txDb.selectMany(table, { name: marker });
+    });
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!["tenantId"]).toBe(testTenantId(1));
+  });
+
+  test("a throw in fn rolls back the tx's own writes", async () => {
+    const tdb = createTenantDb(testDb.db, tenant1.tenantId);
+    const marker = `rollback-${crypto.randomUUID()}`;
+
+    await expect(
+      runInOwnTransaction(tdb, async (txDb) => {
+        await txDb.insertOne(table, { name: marker });
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    const rows = await tdb.selectMany(table, { name: marker });
+    expect(rows).toHaveLength(0);
+  });
+
+  test("commits the tx's writes on success", async () => {
+    const tdb = createTenantDb(testDb.db, tenant1.tenantId);
+    const marker = `commit-${crypto.randomUUID()}`;
+
+    await runInOwnTransaction(tdb, async (txDb) => {
+      await txDb.insertOne(table, { name: marker });
+    });
+
+    const rows = await tdb.selectMany(table, { name: marker });
+    expect(rows).toHaveLength(1);
+  });
+
+  test("throws InternalError for a TenantDb not built by createTenantDb", async () => {
+    const handBuilt = { tenantId: testTenantId(1), mode: "tenant" } as unknown as TenantDb;
+
+    await expect(runInOwnTransaction(handBuilt, async () => undefined)).rejects.toThrow(
+      InternalError,
+    );
+  });
+
+  test("throws InternalError for a throwing guard Proxy, without the proxy's get trap firing", async () => {
+    let getTrapFired = false;
+    const guardProxy = new Proxy(
+      {},
+      {
+        get() {
+          getTrapFired = true;
+          throw new Error("systemScope guard: property access denied");
+        },
+      },
+    ) as unknown as TenantDb;
+
+    await expect(runInOwnTransaction(guardProxy, async () => undefined)).rejects.toThrow(
+      InternalError,
+    );
+    expect(getTrapFired).toBe(false);
+  });
+
+  test("throws InternalError for a memberReadOnly TenantDb", async () => {
+    const tdb = createTenantDb(
+      testDb.db,
+      tenant1.tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { memberReadOnly: true },
+    );
+
+    await expect(runInOwnTransaction(tdb, async () => undefined)).rejects.toThrow(InternalError);
+  });
+
+  test("throws InternalError when the runner has no begin() (already inside a transaction)", async () => {
+    const tdb = createTenantDb(testDb.db, tenant1.tenantId);
+
+    await expect(
+      runInOwnTransaction(tdb, async (txDb) => runInOwnTransaction(txDb, async () => undefined)),
+    ).rejects.toThrow(InternalError);
+  });
+
+  test("a runner-bound personalDataGate (not declared on this TenantDb) still applies on the tx-bound db", async () => {
+    const denyEmail: PersonalDataGate = (_tableName, keys) => {
+      if (keys.includes("email")) {
+        throw new AccessDeniedError({ message: "personal data blocked" });
+      }
+    };
+    const tdb = createTenantDb(
+      testDb.db,
+      tenant1.tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { personalDataGate: denyEmail, unsafeRaw: { reason: "test: derive runner-bound gate" } },
+    );
+    // Mirrors createTenantDb(ctx.db.unsafeRaw(reason), ...): the gate now lives on the
+    // runner, not in this new TenantDb's own (unset) grants.
+    const gatedRunner = tdb.unsafeRaw("test: derive runner-bound gate");
+    const runnerBoundTdb = createTenantDb(gatedRunner, tenant1.tenantId);
+
+    expect(() =>
+      assertPersonalDataWrite(runnerBoundTdb, "run_in_own_tx_items", ["email"], entity),
+    ).toThrow(AccessDeniedError);
+
+    await runInOwnTransaction(runnerBoundTdb, async (txDb) => {
+      expect(() => assertPersonalDataWrite(txDb, "run_in_own_tx_items", ["email"], entity)).toThrow(
+        AccessDeniedError,
+      );
+    });
+  });
+});

package/src/db/index.ts

@@ -157,5 +157,6 @@ export {
   castTenantRows,
   createSystemDbView,
   createTenantDb,
+  runInOwnTransaction,
   SYSTEM_SCOPE_CHECK_BRAND,
 } from "./tenant-db";

package/src/db/query.ts

@@ -17,6 +17,7 @@ export {
   insertMany,
   insertOne,
   type OrderByClause,
+  runInNewTransaction,
   runInSavepoint,
   runInSavepointIfSupported,
   type SelectOptions,

package/src/db/tenant-db.ts

@@ -21,6 +21,7 @@ import {
   insertOne as bunInsertOne,
   selectMany as bunSelectMany,
   updateMany as bunUpdateMany,
+  runInNewTransaction,
   type SelectOptions,
   type WhereObject,
 } from "../db/query";
@@ -378,6 +379,25 @@ export function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: str
   return rebind(reason);
 }
 
+type OwnTransactionRunner = <T>(fn: (txDb: TenantDb) => Promise<T>) => Promise<T>;
+
+const ownTransactionRebinders = new WeakMap<TenantDb, OwnTransactionRunner>();
+
+export async function runInOwnTransaction<T>(
+  tenantDb: TenantDb,
+  fn: (txDb: TenantDb) => Promise<T>,
+): Promise<T> {
+  const rebind = ownTransactionRebinders.get(tenantDb);
+  if (!rebind) {
+    throw new InternalError({
+      message:
+        "runInOwnTransaction received a TenantDb not built by createTenantDb — " +
+        "no transaction rebinder bound.",
+    });
+  }
+  return rebind(fn);
+}
+
 export function createTenantDb(
   db: DbRunner,
   tenantId: TenantId,
@@ -685,6 +705,20 @@ export function createTenantDb(
     report("acknowledge-cross-tenant", reason);
     return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
   });
+  ownTransactionRebinders.set(tenantDb, async (fn) => {
+    if (grants?.memberReadOnly) {
+      throw new InternalError({
+        message:
+          "runInOwnTransaction: memberReadOnly TenantDb — a fresh transaction would escape " +
+          "the enforced read-only scope.",
+      });
+    }
+    // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since the fresh tx-handle isn't itself registered in runnerPersonalDataGates.
+    const txGrants = personalDataGate ? { ...grants, personalDataGate } : grants;
+    return runInNewTransaction(db, (tx) =>
+      fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)),
+    );
+  });
   bindTenantDbRunner(tenantDb, db);
   if (personalDataGate) personalDataGates.set(tenantDb, personalDataGate);
   return tenantDb;

package/src/engine/__tests__/changeset-changes.test.ts

@@ -35,6 +35,15 @@ describe("parseChangesetChanges", () => {
     ]);
   });
 
+  test("keeps a blank line inside a multiline block as a paragraph break, not a truncation", () => {
+    const changes = parseChangesetChanges(
+      `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: breaking\ntitle: Removes the old flow\nmigration: |\n  First paragraph.\n\n  Second paragraph after a blank line.\n-->`,
+      ".changeset/blank-line.md",
+    );
+
+    expect(changes[0]?.migration).toBe("First paragraph.\n\nSecond paragraph after a blank line.");
+  });
+
   test("rejects a breaking change without migration", () => {
     expect(() =>
       parseChangesetChanges(

package/src/engine/changeset-changes.ts

@@ -36,10 +36,23 @@ function parseBlock(raw: string, source: string): ReadonlyMap<string, string> {
     const value = match[2];
     if (value === "|") {
       const continuation: string[] = [];
-      while (index + 1 < lines.length && (lines[index + 1]?.startsWith("  ") ?? false)) {
-        index++;
-        const continuationLine = lines[index];
-        if (continuationLine) continuation.push(continuationLine.slice(2));
+      // A blank line inside the block is a paragraph break, not the end of it;
+      // stopping on the first one truncated the field and then threw a
+      // misleading "invalid line" error on the next indented line, which no
+      // longer looked like a `key: value` pair on its own.
+      while (index + 1 < lines.length) {
+        const next = lines[index + 1] ?? "";
+        if (next.startsWith("  ")) {
+          index++;
+          continuation.push(next.slice(2));
+          continue;
+        }
+        if (next.trim() === "") {
+          index++;
+          continuation.push("");
+          continue;
+        }
+        break;
       }
       fields.set(key, continuation.join("\n").trim());
       continue;

package/src/files/__tests__/files.integration.test.ts

@@ -66,6 +66,7 @@ const testTenantEntity = createEntity({
   fields: {
     name: createTextField({ personal: false, reason: "test_fixture", required: true }),
     logo: createImageField({ maxSize: "2mb", accept: ["png", "jpg"] }),
+    strictLogo: createImageField({ maxSize: "2mb", accept: ["jpg"] }),
     importFile: createFileField({ maxSize: "2mb", accept: ["csv"] }),
   },
 });
@@ -266,8 +267,8 @@ describe("file validation", () => {
   });
 
   test("validateFileContent accepts .doc/.docx bytes matching their declared extension", () => {
-    expect(validateFileContent("report.doc", docBytes)).toBeNull();
-    expect(validateFileContent("report.docx", docxBytes)).toBeNull();
+    expect(validateFileContent("report.doc", docBytes)).toEqual({ kind: "ok" });
+    expect(validateFileContent("report.docx", docxBytes)).toEqual({ kind: "ok" });
   });
 
   test("validateFileContent rejects .doc/.docx whose content doesn't match the extension", () => {
@@ -275,13 +276,15 @@ describe("file validation", () => {
       "fake.doc",
       new TextEncoder().encode("not actually a Word document, just text"),
     );
-    expectErrorIncludes(fakeDoc, "content_mismatch");
+    expect(fakeDoc.kind).toBe("rejected");
+    expectErrorIncludes(fakeDoc.kind === "rejected" ? fakeDoc.error : null, "content_mismatch");
 
     const fakeDocx = validateFileContent(
       "fake.docx",
       new TextEncoder().encode("not actually a docx, just text"),
     );
-    expectErrorIncludes(fakeDocx, "content_mismatch");
+    expect(fakeDocx.kind).toBe("rejected");
+    expectErrorIncludes(fakeDocx.kind === "rejected" ? fakeDocx.error : null, "content_mismatch");
   });
 
   test("validateFileContent now content-verifies every signature-bearing extension (e.g. pdf), not just doc/docx", () => {
@@ -289,23 +292,73 @@ describe("file validation", () => {
       "fake.pdf",
       new TextEncoder().encode("not a PDF at all, just text"),
     );
-    expectErrorIncludes(mismatch, "content_mismatch");
+    expect(mismatch.kind).toBe("rejected");
+    expectErrorIncludes(mismatch.kind === "rejected" ? mismatch.error : null, "content_mismatch");
   });
 
   test("validateFileContent leaves extensions without a magic-byte signature unchecked (csv/txt/svg/md/json/unknown)", () => {
     const text = new TextEncoder().encode("just plain text, not any binary format");
-    expect(validateFileContent("data.csv", text)).toBeNull();
-    expect(validateFileContent("notes.txt", text)).toBeNull();
-    expect(validateFileContent("readme.md", text)).toBeNull();
-    expect(validateFileContent("data.json", text)).toBeNull();
-    expect(validateFileContent("logo.svg", text)).toBeNull();
-    expect(validateFileContent("file.unknownext", text)).toBeNull();
+    expect(validateFileContent("data.csv", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("notes.txt", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("readme.md", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("data.json", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("logo.svg", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("file.unknownext", text)).toEqual({ kind: "ok" });
   });
 
   test("validateFileContent treats a prototype-property extension as unknown instead of crashing", () => {
-    expect(validateFileContent("evil.constructor", docBytes)).toBeNull();
-    expect(validateFileContent("evil.__proto__", docBytes)).toBeNull();
-    expect(validateFileContent("evil.toString", docBytes)).toBeNull();
+    expect(validateFileContent("evil.constructor", docBytes)).toEqual({ kind: "ok" });
+    expect(validateFileContent("evil.__proto__", docBytes)).toEqual({ kind: "ok" });
+    expect(validateFileContent("evil.toString", docBytes)).toEqual({ kind: "ok" });
+  });
+
+  const pngBytesForNormalization = new Uint8Array([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    ...Array(20).fill(0),
+  ]);
+
+  test("validateFileContent normalizes PNG bytes uploaded as .jpg when png is in accept", () => {
+    expect(validateFileContent("photo.jpg", pngBytesForNormalization, ["jpg", "png"])).toEqual({
+      kind: "normalized",
+      extension: "png",
+      mimeType: "image/png",
+    });
+  });
+
+  test("validateFileContent still rejects PNG bytes uploaded as .jpg when png is not in accept", () => {
+    const result = validateFileContent("photo.jpg", pngBytesForNormalization, ["jpg"]);
+    expect(result.kind).toBe("rejected");
+  });
+
+  test("validateFileContent rejects a format not covered by accept at all, even with accept present", () => {
+    const result = validateFileContent("photo.jpg", new TextEncoder().encode("%PDF-1.4 minimal"), [
+      "jpg",
+      "png",
+    ]);
+    expect(result.kind).toBe("rejected");
+  });
+
+  test("validateFileContent without an accept list normalizes too — no accept means no restriction to widen", () => {
+    expect(validateFileContent("photo.jpg", pngBytesForNormalization)).toEqual({
+      kind: "normalized",
+      extension: "png",
+      mimeType: "image/png",
+    });
+  });
+
+  test("validateFileContent with an empty accept list normalizes the same as no accept at all", () => {
+    expect(validateFileContent("photo.jpg", pngBytesForNormalization, [])).toEqual({
+      kind: "normalized",
+      extension: "png",
+      mimeType: "image/png",
+    });
   });
 
   test("validateFile with accept: ['constructor'] and a matching filename never throws", () => {
@@ -667,7 +720,7 @@ describe("content_mismatch is enforced by filename extension for every signature
   ]);
   const docxBytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, ...Array(20).fill(0)]);
 
-  test("PDF bytes uploaded as x.jpg against an accept: [jpg] field are rejected with content_mismatch", async () => {
+  test("PDF bytes uploaded as x.jpg against an accept: [png, jpg] field are rejected with content_mismatch", async () => {
     const res = await uploadFile(adminUser, "x.jpg", pdfBytes, "image/jpeg", {
       entityType: "tenant",
       entityId: "1",
@@ -678,6 +731,44 @@ describe("content_mismatch is enforced by filename extension for every signature
     expect(body.error).toContain("content_mismatch");
   });
 
+  test("PNG bytes uploaded as x.jpg are normalized and stored as image/png when png is in the field's accept", async () => {
+    const res = await uploadFile(adminUser, "x.jpg", pngBytes, "image/jpeg", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "logo",
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.fileName).toBe("x.jpg");
+    expect(body.mimeType).toBe("image/png");
+    expect(body.storageKey).toMatch(/\.png$/);
+  });
+
+  test("PNG bytes normalized on upload are served back with the matching image/png Content-Type", async () => {
+    const uploadRes = await uploadFile(adminUser, "x.jpg", pngBytes, "image/jpeg", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "logo",
+    });
+    expect(uploadRes.status).toBe(201);
+    const { id } = await uploadRes.json();
+
+    const res = await getFile(adminUser, id);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/png");
+  });
+
+  test("PNG bytes uploaded as x.jpg against a field whose accept doesn't include png are still rejected with content_mismatch", async () => {
+    const res = await uploadFile(adminUser, "x.jpg", pngBytes, "image/jpeg", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "strictLogo",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("content_mismatch");
+  });
+
   test("real signature bytes with a matching extension upload successfully", async () => {
     for (const [fileName, bytes, mimeType] of [
       ["real.jpg", jpegBytes, "image/jpeg"],
@@ -710,6 +801,15 @@ describe("content_mismatch is enforced by filename extension for every signature
     expect(protoRes.status).toBe(201);
   });
 
+  test("an unattached upload (no entityType/fieldName, so no accept restriction) also normalizes mislabeled bytes", async () => {
+    const res = await uploadFile(adminUser, "vin.jpg", pngBytes, "image/jpeg");
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.fileName).toBe("vin.jpg");
+    expect(body.mimeType).toBe("image/png");
+    expect(body.storageKey).toMatch(/\.png$/);
+  });
+
   test("a too-short .png upload (fewer bytes than the PNG signature) is rejected with content_mismatch", async () => {
     // A zero-byte file part is dropped by Bun's multipart parser before it
     // ever reaches the route handler as `file`, so this uses one byte

package/src/files/file-routes.ts

@@ -224,6 +224,27 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       return c.json({ error: validationError }, 400);
     }
 
+    const data = new Uint8Array(await file.arrayBuffer());
+
+    const contentValidation = validateFileContent(file.name, data, accept);
+    if (contentValidation.kind === "rejected") {
+      return c.json({ error: contentValidation.error }, 400);
+    }
+
+    // A normalized upload's real type is already known from the sniffed
+    // bytes — resolveUploadMimeType's alias/rewrite step only applies to the
+    // declared mimeType of an unnormalized upload.
+    let mimeType: string;
+    if (contentValidation.kind === "normalized") {
+      mimeType = contentValidation.mimeType;
+    } else {
+      const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
+      if (mimeTypeResolution.kind === "rejected") {
+        return c.json({ error: mimeTypeResolution.error }, 400);
+      }
+      mimeType = mimeTypeResolution.mimeType;
+    }
+
     const fileRefId = generateId();
     const storageKey = buildStorageKey(
       user.tenantId,
@@ -232,21 +253,9 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       fieldName ?? "file",
       file.name,
       generateId(),
+      contentValidation.kind === "normalized" ? contentValidation.extension : undefined,
     );
 
-    const data = new Uint8Array(await file.arrayBuffer());
-
-    const contentValidationError = validateFileContent(file.name, data);
-    if (contentValidationError) {
-      return c.json({ error: contentValidationError }, 400);
-    }
-
-    const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
-    if (mimeTypeResolution.kind === "rejected") {
-      return c.json({ error: mimeTypeResolution.error }, 400);
-    }
-    const mimeType = mimeTypeResolution.mimeType;
-
     // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
     // inside a PG connection's tx window). On DB-tx rollback below the bytes
     // are orphaned in the provider; cleanup-jobs sweep those later. Losing a

package/src/files/index.ts

@@ -33,6 +33,7 @@ export {
   transferTenantStorageUsage,
 } from "./storage-tracking";
 export type {
+  FileContentValidationResult,
   FileMetadata,
   FileStorageProvider,
   FileValidationOptions,

package/src/files/types.ts

@@ -79,6 +79,15 @@ function lookupExtensionWhitelist(ext: string): readonly string[] | undefined {
   return EXTENSION_MIME_WHITELIST[ext];
 }
 
+// Reverse of lookupExtensionWhitelist: every extension whose whitelist entry
+// includes this MIME type (e.g. "image/jpeg" -> ["jpg", "jpeg"]) — backs
+// validateFileContent's accept-based normalization below.
+function extensionsForMimeType(mimeType: string): readonly string[] {
+  return Object.entries(EXTENSION_MIME_WHITELIST)
+    .filter(([, mimeTypes]) => mimeTypes.includes(mimeType))
+    .map(([ext]) => ext);
+}
+
 // Magic-byte signatures for the subset of EXTENSION_MIME_WHITELIST that has
 // a reliable binary signature. Used both at upload time (validateFileContent)
 // and at serve time (resolveServedContentType) — never trust the stored/
@@ -217,17 +226,48 @@ function signatureMimeTypesForExtension(ext: string): readonly string[] {
   );
 }
 
+export type FileContentValidationResult =
+  | { readonly kind: "ok" }
+  | { readonly kind: "normalized"; readonly extension: string; readonly mimeType: string }
+  | { readonly kind: "rejected"; readonly error: string };
+
 // Separate from validateFile: metadata is known before the upload body is
 // fully read, content-verification only after — callers reject early on
 // metadata without buffering bytes they'll then have to reject anyway.
-export function validateFileContent(fileName: string, content: Uint8Array): string | null {
+//
+// When the sniffed signature doesn't match the declared extension but the
+// sniffed type's OWN extension is in a non-empty `accept`, the upload
+// normalizes to that type instead of being rejected — this only widens which
+// of the field's own allowed formats a mislabeled upload can settle into,
+// never which formats are accepted. With no `accept` restriction at all
+// (undefined or empty, same "unrestricted" meaning validateFile gives it),
+// any recognized signature normalizes the same way, since there is no
+// declared list left to widen.
+export function validateFileContent(
+  fileName: string,
+  content: Uint8Array,
+  accept?: readonly string[],
+): FileContentValidationResult {
   const ext = extractExtension(fileName);
-  if (!ext) return null;
+  if (!ext) return { kind: "ok" };
   const signatureMimeTypes = signatureMimeTypesForExtension(ext);
-  if (signatureMimeTypes.length === 0) return null;
+  if (signatureMimeTypes.length === 0) return { kind: "ok" };
   const sniffed = sniffMimeType(content);
-  if (sniffed && signatureMimeTypes.includes(sniffed)) return null;
-  return `content_mismatch: ".${ext}" upload bytes are ${sniffed ?? "unrecognized"}, expected ${signatureMimeTypes.join(" or ")}`;
+  if (sniffed && signatureMimeTypes.includes(sniffed)) return { kind: "ok" };
+  if (sniffed) {
+    const candidateExtensions = extensionsForMimeType(sniffed);
+    const hasAcceptRestriction = accept !== undefined && accept.length > 0;
+    const normalizedExtension = hasAcceptRestriction
+      ? candidateExtensions.find((candidate) => accept.includes(candidate))
+      : candidateExtensions[0];
+    if (normalizedExtension) {
+      return { kind: "normalized", extension: normalizedExtension, mimeType: sniffed };
+    }
+  }
+  return {
+    kind: "rejected",
+    error: `content_mismatch: ".${ext}" upload bytes are ${sniffed ?? "unrecognized"}, expected ${signatureMimeTypes.join(" or ")}`,
+  };
 }
 
 export type UploadMimeTypeResolution =
@@ -270,8 +310,12 @@ export function buildStorageKey(
   fieldName: string,
   fileName: string,
   uniqueId: string,
+  // Set when validateFileContent normalized the upload to a different real
+  // type — the storage key then reflects the sniffed type, not the user's
+  // (wrong) original extension.
+  extensionOverride?: string,
 ): string {
-  const rawExt = fileName.split(".").pop() ?? "";
+  const rawExt = extensionOverride ?? fileName.split(".").pop() ?? "";
   const ext = /^[A-Za-z0-9]+$/.test(rawExt) ? rawExt.toLowerCase() : "bin";
   return `${tenantId}/${entityType}/${entityId}/${fieldName}/${uniqueId}.${ext}`;
 }