@cosmicdrift/kumiko-framework 0.313.0 → 0.315.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.313.0",
+  "version": "0.315.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.313.0",
-    "@cosmicdrift/kumiko-types": "0.313.0",
+    "@cosmicdrift/kumiko-http": "0.315.0",
+    "@cosmicdrift/kumiko-types": "0.315.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.313.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.315.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/upgrade-cli.test.ts

@@ -564,6 +564,34 @@ describe("upgrade command — filter baseline is the marker, not the installed v
     // rather than filtered out entirely by a too-high baseline.
     expect(updatedMarker.version).toBe("0.188.0");
     expect(updatedMarker.version).not.toBe("0.195.0");
+    expect(spy.logs.join("\n")).toContain(
+      "Marker moved past the manual change(s) above to 0.188.0",
+    );
+  });
+
+  test("a manual breaking change is acknowledged by a second --apply after the first one held the marker back", async () => {
+    const fixEntry = { version: "0.310.0", type: "fix", title: "earlier fix" };
+    const manualEntry = { version: "0.311.0", type: "breaking", title: "manual breaking change" };
+    const cwd = tmp({
+      "packages/framework/src/changes.json": JSON.stringify([fixEntry, manualEntry]),
+      "packages/bundled-features/package.json": JSON.stringify({ version: "0.311.0" }),
+      ".kumiko/upgrade-state.json": marker("0.309.0"),
+    });
+    const markerPath = join(cwd, ".kumiko/upgrade-state.json");
+
+    const firstRun = makeSpyOutput();
+    expect(await runUpgradeCli(["--apply"], cwd, firstRun.out, { repoRoot: REAL_REPO_ROOT })).toBe(
+      0,
+    );
+    expect(JSON.parse(readFileSync(markerPath, "utf-8")).version).toBe("0.310.0");
+    expect(firstRun.logs.join("\n")).toContain("Marker stays at 0.310.0");
+
+    const secondRun = makeSpyOutput();
+    expect(await runUpgradeCli(["--apply"], cwd, secondRun.out, { repoRoot: REAL_REPO_ROOT })).toBe(
+      0,
+    );
+    expect(secondRun.logs.join("\n")).toContain("no codemod, manual migration required");
+    expect(JSON.parse(readFileSync(markerPath, "utf-8")).version).toBe("0.311.0");
   });
 
   test("bare --apply with no marker (bootstrap): behaves as before, marker is written at the installed version", async () => {

package/src/api/__tests__/origin-middleware.integration.test.ts

@@ -9,8 +9,10 @@
 // rejected them (guards return 403).
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";
-import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "../auth-middleware";
+import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, getUser } from "../auth-middleware";
 
 const ALLOWED = "https://admin.example.eu";
 const DISALLOWED = "https://tenant.example.eu";
@@ -130,3 +132,142 @@ describe("origin-middleware opt-out (unsafeSkipOriginCheck)", () => {
     expect(await errorCode(res)).toBe("csrf_token_mismatch");
   });
 });
+
+// The "without anonymousAccess" case (disallowed origin → 403) is already
+// covered above by the first describe block's server config, minus
+// anonymousAccess — not repeated here.
+const anonEchoQuery = { type: "origin-anon-probe:query:anon-echo", payload: {} };
+const userOnlyRoute = { type: "origin-anon-probe:write:user-only", payload: {} };
+const probeFeature = defineFeature("origin-anon-probe", (r) => {
+  r.queryHandler({
+    name: "anon-echo",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    handler: async (event) => ({ userId: event.user.id, roles: event.user.roles }),
+  });
+  r.writeHandler({
+    name: "user-only",
+    schema: z.object({}),
+    access: { roles: ["User"] },
+    handler: async (event) => ({
+      isSuccess: true as const,
+      data: { userId: event.user.id, roles: event.user.roles },
+    }),
+  });
+  // anonymous:false httpRoutes can't live under /api/* — the boot validator
+  // (feature-ui-extensions.ts) hard-blocks that path prefix for every
+  // feature route, so this is mounted outside /api/* and guarded by
+  // sessionOnlyHttpRouteGuards (sessionOnlyGuard, no foreignCookieOrigins
+  // downgrade) instead of the /api/* jwtGuard used above.
+  r.httpRoute({
+    method: "POST",
+    path: "/origin-anon-probe-http",
+    anonymous: false,
+    handler: async (c) => c.json({ id: getUser(c).id }),
+  });
+});
+
+describe("origin-middleware + anonymousAccess: foreign-origin cookie becomes anonymous", () => {
+  let stack: TestStack;
+  let authCookie: string;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [probeFeature],
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        allowedOrigins: [ALLOWED],
+        cookieDomain: "example.eu",
+      },
+      anonymousAccess: { defaultTenantId: TestUsers.user.tenantId },
+    });
+    const token = await stack.jwt.sign(TestUsers.user);
+    authCookie = `${AUTH_COOKIE_NAME}=${token}`;
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("foreign origin + cookie, no CSRF token → handler runs as the anonymous user", async () => {
+    const res = await stack.http.raw("POST", "/api/query", anonEchoQuery, {
+      Cookie: authCookie,
+      Origin: DISALLOWED,
+    });
+    // 200 (not csrf_token_mismatch) proves CSRF wasn't required — authTransport
+    // stayed unset — and the echoed identity is the synthesised anonymous
+    // user, not the cookie's real one.
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { userId: string; roles: readonly string[] } };
+    expect(body.data.userId).toBe("anonymous");
+    expect(body.data.roles).toEqual(["anonymous"]);
+  });
+
+  test("foreign origin + garbage cookie value → still anonymous, jwt.verify never runs", async () => {
+    const res = await stack.http.raw("POST", "/api/query", anonEchoQuery, {
+      Cookie: `${AUTH_COOKIE_NAME}=not-a-valid-jwt`,
+      Origin: DISALLOWED,
+    });
+    // A malformed token would 401 invalid_token if jwt.verify ran on it —
+    // 200 here is only possible if the cookie was dropped unread.
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { userId: string } };
+    expect(body.data.userId).toBe("anonymous");
+  });
+
+  test("/api/auth/logout from a foreign origin → still 403 origin_not_allowed, not silently anonymous", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/auth/logout",
+      {},
+      {
+        Cookie: authCookie,
+        Origin: DISALLOWED,
+      },
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+
+  test("allowed origin + cookie, no CSRF token → real user path still requires CSRF", async () => {
+    const res = await stack.http.raw("POST", "/api/write", userOnlyRoute, {
+      Cookie: authCookie,
+      Origin: ALLOWED,
+    });
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("csrf_token_mismatch");
+  });
+
+  test("allowed origin + cookie + valid CSRF → authenticated as the real user, not anonymous", async () => {
+    const csrf = "csrf-fixed-anon-fallthrough-token";
+    const res = await stack.http.raw("POST", "/api/write", userOnlyRoute, {
+      Cookie: `${authCookie}; ${CSRF_COOKIE_NAME}=${csrf}`,
+      Origin: ALLOWED,
+      [CSRF_HEADER_NAME]: csrf,
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { userId: string; roles: readonly string[] } };
+    expect(body.data.userId).toBe(TestUsers.user.id);
+    expect(body.data.roles).toEqual(TestUsers.user.roles);
+  });
+
+  test("anonymous:false r.httpRoute, foreign origin + cookie, no CSRF → 403 origin_not_allowed, sessionOnlyGuard does not downgrade to anonymous", async () => {
+    // /api/* would downgrade a foreign-origin cookie to anonymous (see the
+    // anon-echo tests above) because jwtGuard carries foreignCookieOrigins.
+    // r.httpRoute anonymous:false routes run behind sessionOnlyGuard instead,
+    // which was deliberately built WITHOUT anonymousAccess/foreignCookieOrigins
+    // — a real cookie must still resolve to the real user, so the Origin guard
+    // rejects it outright instead of silently falling through anonymous.
+    const res = await stack.http.raw(
+      "POST",
+      "/origin-anon-probe-http",
+      {},
+      {
+        Cookie: authCookie,
+        Origin: DISALLOWED,
+      },
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+});

package/src/api/auth-middleware.ts

@@ -6,6 +6,7 @@ import type { SessionUser, TenantId } from "../engine/types";
 import { parseTenantId } from "../engine/types/identifiers";
 import { TENANT_COOKIE_NAME, TENANT_HEADER_NAME } from "./api-constants";
 import type { JwtHelper } from "./jwt";
+import { isForeignCookieOrigin } from "./origin-middleware";
 
 const USER_KEY = "pipelineUser";
 const AUTH_TRANSPORT_KEY = "authTransport";
@@ -92,6 +93,14 @@ export type AuthMiddlewareOptions = {
   // when the tenant is in teardown (destroyRequested/destroying/destroyed).
   // cancel-destruction is exempt while status=destroyRequested.
   readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
+  // Normalized auth.allowedOrigins. A cookie from an origin outside this set
+  // is dropped BEFORE jwt.verify — treated as if no cookie was sent — and
+  // falls through to the anonymousAccess flow instead of the 403 the
+  // sibling originMiddleware would give (fw#340: a public status page's
+  // session cookie, set on the base domain, reaches every tenant subdomain
+  // even though those pages only ever make anonymous queries). Only
+  // meaningful together with anonymousAccess.
+  readonly foreignCookieOrigins?: ReadonlySet<string>;
 };
 
 // Resolves the tenant for an unauthenticated request. Returns null when no
@@ -205,7 +214,13 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus } = options;
+  const {
+    sessionChecker,
+    anonymousAccess,
+    tokenVerifier,
+    resolveTenantLifecycleStatus,
+    foreignCookieOrigins,
+  } = options;
 
   // Fail loud at boot, not silently at request time: a tenantResolver
   // without a declared resolverTrust is an ambiguous trust decision no
@@ -259,6 +274,20 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
     const { token, transport } = extracted;
 
+    // A foreign-origin cookie is noise, not an authentication attempt worth
+    // verifying — drop it before jwt.verify, the token is never read. Auth
+    // routes are excluded (same reasoning as the missing-token branch above):
+    // logout must still see the real auth state, not be silently downgraded.
+    if (
+      transport === "cookie" &&
+      anonymousAccess &&
+      !c.req.path.startsWith("/api/auth/") &&
+      foreignCookieOrigins &&
+      isForeignCookieOrigin(c, foreignCookieOrigins)
+    ) {
+      return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+    }
+
     // Generic bearer-verifier path: try the wired tokenVerifier (PAT, future
     // JWT-provider, ...) BEFORE jwt.verify. A hit short-circuits the JWT path
     // entirely; a miss (null — no provider's shape matched, or the matching

package/src/api/origin-middleware.ts

@@ -16,6 +16,21 @@ export function isOriginAllowed(origin: string, normalizedAllowlist: ReadonlySet
   return normalizedAllowlist.has(normalizeOrigin(origin));
 }
 
+// True when a state-changing request carries an Origin (or Sec-Fetch-Site)
+// signal that marks it as coming from outside the allowlist.
+export function isForeignCookieOrigin(c: Context, allowlist: ReadonlySet<string>): boolean {
+  if (!STATE_CHANGING_METHODS.has(c.req.method)) return false;
+
+  const origin = c.req.header("origin");
+  if (origin !== undefined) return !isOriginAllowed(origin, allowlist);
+
+  // No Origin header — older browsers, and some same-origin POSTs in Safari.
+  // Fall back to the Fetch-Metadata Sec-Fetch-Site signal: only an explicit
+  // cross-site marker counts as foreign here (it's a relation, not an origin,
+  // so it can't be matched against the allowlist).
+  return c.req.header("sec-fetch-site") === "cross-site";
+}
+
 function rejectOrigin(c: Context): Response {
   return c.json(
     {
@@ -49,26 +64,14 @@ export function originMiddleware(allowedOrigins: readonly string[]) {
   return async (c: Context, next: Next) => {
     const transport = getAuthTransport(c);
     if (transport !== "cookie") return next();
-    if (!STATE_CHANGING_METHODS.has(c.req.method)) return next();
-
-    const origin = c.req.header("origin");
-    if (origin !== undefined) {
-      if (isOriginAllowed(origin, allowlist)) return next();
-      return rejectOrigin(c);
-    }
-
-    // No Origin header — older browsers, and some same-origin POSTs in Safari.
-    // Fall back to the Fetch-Metadata Sec-Fetch-Site signal: only an explicit
-    // cross-site marker is blocked here (it's a relation, not an origin, so it
-    // can't be matched against the allowlist). Everything else (same-site,
-    // same-origin, none, absent) falls through to the CSRF token. Note: the
-    // CSRF token alone does NOT stop a same-site subdomain XSS — it can read
-    // the wide cookie — but that attack uses fetch/XHR, which always sends an
-    // Origin header and is already rejected by the allowlist branch above. The
-    // residual is only the no-Origin-yet-Sec-Fetch-Site combo, which no current
-    // browser emits for state-changing requests.
-    if (c.req.header("sec-fetch-site") === "cross-site") return rejectOrigin(c);
-
+    // Everything else (same-site, same-origin, none, absent) falls through to
+    // the CSRF token. Note: the CSRF token alone does NOT stop a same-site
+    // subdomain XSS — it can read the wide cookie — but that attack uses
+    // fetch/XHR, which always sends an Origin header and is already rejected
+    // by the allowlist branch inside isForeignCookieOrigin. The residual is
+    // only the no-Origin-yet-Sec-Fetch-Site combo, which no current browser
+    // emits for state-changing requests.
+    if (isForeignCookieOrigin(c, allowlist)) return rejectOrigin(c);
     return next();
   };
 }

package/src/api/server.ts

@@ -71,7 +71,7 @@ import {
 } from "./extra-route";
 import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
-import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
+import { assertOriginGuardConfig, normalizeOrigin, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
 import { createDefaultSseBroker, type RedisSseBroker } from "./redis-sse-broker";
 import { requestContext } from "./request-context";
@@ -726,11 +726,20 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const tenantLifecycleResolver =
     options.auth?.resolveTenantLifecycleStatus ??
     deriveTenantLifecycleResolver(options.registry, baseDb);
+  // sessionOnlyGuard deliberately does NOT get this — its callers have no
+  // anonymousAccess fallback, so a foreign-origin cookie there must keep
+  // failing through the sibling originMiddleware 403.
+  const normalizedForeignCookieOrigins = options.auth?.allowedOrigins?.length
+    ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
+    : undefined;
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
     ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
+    ...(normalizedForeignCookieOrigins
+      ? { foreignCookieOrigins: normalizedForeignCookieOrigins }
+      : {}),
   });
   app.use("/api/*", async (c, next) => {
     if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();

package/src/changes.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "0.315.0",
+    "type": "breaking",
+    "title": "files: content verification is now keyed by filename extension, covering every signature-bearing type",
+    "migration": "validateFileContent's signature changes from (mimeType: string, content: Uint8Array) to (fileName: string, content: Uint8Array): string | null. It now content-verifies every extension whose EXTENSION_MIME_WHITELIST entry overlaps MAGIC_BYTE_SIGNATURES (jpg/jpeg/png/gif/webp/pdf/doc/docx), not just doc/docx, and derives the check declaratively from the whitelist instead of a hardcoded per-format list. file-routes.ts now passes file.name instead of file.type (Bun derives File#type from the filename anyway, so the mimeType-keyed call was already comparing an extension-derived value to itself). A malicious extension shaped like a JS prototype property (constructor, __proto__, toString) resolves to \"unknown extension\" (no error) instead of crashing with a 500 — the same Object.hasOwn-guarded whitelist lookup is now shared by validateFile and validateFileContent. mime_mismatch remains a metadata-only pre-check; it is not real evidence of file content. Any test that uploads placeholder bytes (e.g. [1,2,3]) through the real upload route under one of the now-verified extensions must switch to real minimal signature bytes or a differently-named/unchecked extension."
+  },
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "drainEventConsumers helper for test stacks with a named consumer backlog",
+    "detail": "The `while ((await eventDispatcher.runOnce())?.processed ?? 0) > 0) {}`\npattern under-drains a backlog bigger than one dispatcher batch and gives no\ndiagnostics when a consumer is stuck. drainEventConsumers(stack,\nconsumerNames, { maxPasses }) from @cosmicdrift/kumiko-framework/stack\nsnapshots the events high-water mark at call time and runs bounded passes\nuntil every named consumer's cursor reaches it, throwing with per-consumer\nstatus, attempts and lastError when the budget (default 25) is exhausted.\nEvents written by consumers after the snapshot are not waited on. No\nmigration needed."
+  },
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "validateFile/resolveUploadMimeType accept .csv declared as application/vnd.ms-excel",
+    "detail": "Windows derives a file's upload MIME type from its Explorer file-type\nassociation rather than its content — .csv is registered to Excel there,\nso a Windows browser can declare \"application/vnd.ms-excel\" for a\nplain-text CSV. validateFile now accepts that declared/extension\ncombination for fields whose `accept` includes \"csv\" instead of rejecting\nit as a `mime_mismatch`. The built-in multipart upload route also calls the\nnew `resolveUploadMimeType`, which rewrites an aliased declared mimeType to\nits canonical form (\"text/csv\") after checking the uploaded bytes against\nknown binary signatures — a match (e.g. a real .xls/.xlsx renamed to .csv)\nis rejected with `content_mismatch` instead of being silently rewritten.\nNote: on Bun 1.4.0 (this repo's pinned engines/Dockerfile version, verified\nlocally), `Request#formData()` derives a multipart file's `.type` from its\nfilename extension rather than the part's declared Content-Type, so a\nbrowser's declared \"application/vnd.ms-excel\" for a `.csv` file does not\ncurrently reach the built-in route as such — callers that read a declared\nmimeType from elsewhere (e.g. a separate form field) are the ones this\nalias helps today. Aliases are declarative per extension; only\ncsv → vnd.ms-excel is defined so far.\n`@cosmicdrift/kumiko-framework/files` now also exports `sniffMimeType(bytes:\nUint8Array): string | null` (canonical MIME for a known binary signature,\nor null for text formats — every OLE Compound File returns\n\"application/msword\" and every ZIP returns the docx MIME, callers can't\ntell those apart by bytes alone) and `resolveUploadMimeType`."
+  },
+  {
+    "version": "0.314.0",
+    "type": "fix",
+    "title": "Foreign-origin cookie on an anonymousAccess server is treated as anonymous, not 403",
+    "detail": "originMiddleware rejected any state-changing request whose cookie-carrying\nOrigin (or Sec-Fetch-Site) fell outside auth.allowedOrigins with 403\norigin_not_allowed, including a logged-in tenant admin's own session cookie\nsent along by their public status page, which only makes anonymous queries.\nOn servers with anonymousAccess wired, authMiddleware now drops such a\nforeign-origin cookie before jwt.verify and falls through to the anonymous\nflow; the token is never read. Servers without anonymousAccess, /api/auth/*\npaths and session-only httpRoutes keep the 403. No migration needed."
+  },
+  {
+    "version": "0.314.0",
+    "type": "fix",
+    "title": "setupTestStack isolates job queues per stack by default",
+    "detail": "BullMQ queues live on the raw Redis URL, outside the per-test keyPrefix, so\ntwo parallel test stacks with `jobs` and no explicit `queueNamePrefix` shared\nthe prod default queue names and one stack's consumer could run the other\nstack's jobs. setupTestStack/setupAppTestStack now derive a unique\n`queueNamePrefix` from the stack's test Redis keyPrefix. An explicit\n`jobs.queueNamePrefix` still wins; pass the same value to every runner that\nhas to share a stack's queues. createJobRunner and the prod path are unchanged."
+  },
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "kumiko-upgrade --apply says where the marker landed relative to manual breaking changes",
+    "detail": "A breaking change without a codemod was listed as \"manual migration\nrequired\", but the run never said whether the upgrade marker stopped below\nit (the guard keeps listing it until a second --apply acknowledges it) or\nalready moved past it (the guard no longer lists it). --apply now prints\nwhich of the two happened. The marker logic itself is unchanged; the\nacknowledgement path is documented in docs/reference/stability-policy.md."
+  },
   {
     "version": "0.313.0",
     "type": "fix",

package/src/derivatives/__tests__/derivatives-context.integration.test.ts

@@ -103,7 +103,7 @@ afterAll(async () => {
 
 async function uploadFile(
   asUser = user,
-  file = new File([Buffer.from([1, 2, 3])], "photo.jpg", { type: "image/jpeg" }),
+  file = new File([Buffer.from([0xff, 0xd8, 0xff, 0xe0])], "photo.jpg", { type: "image/jpeg" }),
 ): Promise<string> {
   const token = await stack.jwt.sign(asUser);
   const fd = new FormData();
@@ -214,7 +214,9 @@ describe("ctx.derivatives — typed errors from variant()", () => {
   test("no renderer registered for the mimeType throws InternalError with httpStatus 500", async () => {
     const fileId = await uploadFile(
       user,
-      new File([Buffer.from([1, 2, 3])], "doc.pdf", { type: "application/pdf" }),
+      new File([Buffer.from(new TextEncoder().encode("%PDF-1.4 minimal"))], "doc.pdf", {
+        type: "application/pdf",
+      }),
     );
 
     const result = await stack.http.writeOk<{

package/src/derivatives/__tests__/variant-route.integration.test.ts

@@ -73,7 +73,10 @@ async function uploadFile(
 ): Promise<string> {
   const token = await stack.jwt.sign(asUser);
   const fd = new FormData();
-  fd.append("file", new File([Buffer.from([1, 2, 3])], "avatar.jpg", { type: "image/jpeg" }));
+  fd.append(
+    "file",
+    new File([Buffer.from([0xff, 0xd8, 0xff, 0xe0])], "avatar.jpg", { type: "image/jpeg" }),
+  );
   if (attach !== null) {
     fd.append("entityType", attach.entityType);
     fd.append("fieldName", attach.fieldName);
@@ -198,7 +201,12 @@ describe("GET /api/files/:id/variant/:name", () => {
   test("a source mimeType with no matching renderer (client uploaded a non-image) returns 415, not a 500", async () => {
     const token = await stack.jwt.sign(user);
     const fd = new FormData();
-    fd.append("file", new File([Buffer.from([1, 2, 3])], "doc.pdf", { type: "application/pdf" }));
+    fd.append(
+      "file",
+      new File([Buffer.from(new TextEncoder().encode("%PDF-1.4 minimal"))], "doc.pdf", {
+        type: "application/pdf",
+      }),
+    );
     fd.append("entityType", "photo");
     fd.append("fieldName", "avatar");
     const { body, contentType } = await buildMultipartBody(fd);

package/src/files/__tests__/file-field-pipeline.integration.test.ts

@@ -89,6 +89,20 @@ beforeEach(async () => {
   await asRawClient(stack.db).unsafe(`TRUNCATE pipeline_documents`);
 });
 
+const PDF_BYTES = new TextEncoder().encode("%PDF-1.4 minimal");
+const JPEG_BYTES = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, ...Array(10).fill(0)]);
+const PNG_BYTES = new Uint8Array([
+  0x89,
+  0x50,
+  0x4e,
+  0x47,
+  0x0d,
+  0x0a,
+  0x1a,
+  0x0a,
+  ...Array(10).fill(0),
+]);
+
 async function uploadFile(fileName: string, body: Uint8Array, mimeType: string): Promise<string> {
   const token = await stack.jwt.sign(user);
   const fd = new FormData();
@@ -107,8 +121,8 @@ async function uploadFile(fileName: string, body: Uint8Array, mimeType: string):
 
 describe("file/image field through the CRUD pipeline", () => {
   test("create entity with file-field UUID → detail round-trips the UUID", async () => {
-    const fileId = await uploadFile("doc.pdf", new Uint8Array([1, 2, 3]), "application/pdf");
-    const imageId = await uploadFile("cover.png", new Uint8Array([4, 5, 6]), "image/png");
+    const fileId = await uploadFile("doc.pdf", PDF_BYTES, "application/pdf");
+    const imageId = await uploadFile("cover.png", PNG_BYTES, "image/png");
 
     // Create through the standard write pipeline — this is the path where the
     // pre-fix validation (z.number() for file/image) would have rejected the
@@ -135,8 +149,8 @@ describe("file/image field through the CRUD pipeline", () => {
   });
 
   test("update entity swaps file-field UUIDs cleanly", async () => {
-    const oldFile = await uploadFile("v1.pdf", new Uint8Array([1]), "application/pdf");
-    const newFile = await uploadFile("v2.pdf", new Uint8Array([2]), "application/pdf");
+    const oldFile = await uploadFile("v1.pdf", PDF_BYTES, "application/pdf");
+    const newFile = await uploadFile("v2.pdf", PDF_BYTES, "application/pdf");
 
     const created = await stack.http.writeOk<{ id: string }>(
       "pipeline-documents:write:document:create",
@@ -177,9 +191,9 @@ describe("file/image field through the CRUD pipeline", () => {
     // files/images) — the array of UUIDs lives in the event payload. The
     // pipeline still has to validate + accept it. Pre-fix this was
     // z.array(z.number()) which would have rejected every UUID array.
-    const a = await uploadFile("a.jpg", new Uint8Array([1]), "image/jpeg");
-    const b = await uploadFile("b.jpg", new Uint8Array([2]), "image/jpeg");
-    const c = await uploadFile("notes.pdf", new Uint8Array([3]), "application/pdf");
+    const a = await uploadFile("a.jpg", JPEG_BYTES, "image/jpeg");
+    const b = await uploadFile("b.jpg", JPEG_BYTES, "image/jpeg");
+    const c = await uploadFile("notes.pdf", PDF_BYTES, "application/pdf");
 
     const created = await stack.http.writeOk<{ id: string }>(
       "pipeline-documents:write:document:create",
@@ -190,8 +204,8 @@ describe("file/image field through the CRUD pipeline", () => {
 
     // Follow-up update: swap one photo out, add a second doc. Proves the
     // update-path handles plural arrays too, not just create.
-    const d = await uploadFile("c.jpg", new Uint8Array([4]), "image/jpeg");
-    const e = await uploadFile("more.pdf", new Uint8Array([5]), "application/pdf");
+    const d = await uploadFile("c.jpg", JPEG_BYTES, "image/jpeg");
+    const e = await uploadFile("more.pdf", PDF_BYTES, "application/pdf");
 
     const updated = await stack.http.writeOk<{ id: string }>(
       "pipeline-documents:write:document:update",
@@ -204,7 +218,7 @@ describe("file/image field through the CRUD pipeline", () => {
   });
 
   test("plural files field rejects non-UUID element (schema validates EACH array element)", async () => {
-    const valid = await uploadFile("ok.pdf", new Uint8Array([1]), "application/pdf");
+    const valid = await uploadFile("ok.pdf", PDF_BYTES, "application/pdf");
     const err = await stack.http.writeErr(
       "pipeline-documents:write:document:create",
       { title: "Bad array", docs: [valid, "not-a-uuid"] },