@antasphere/chassis-server 1.0.0

package/test/integration/export-entries.test.ts

@@ -0,0 +1,321 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import AdmZip from 'adm-zip';
+import { eq } from 'drizzle-orm';
+import { workspaces, type Db } from '@antasphere/chassis-db';
+import { createPlatform, type ExportEntry, type ToolDefinition } from '@antasphere/chassis-server';
+import {
+  createDatabase,
+  extractCookie,
+  makeCreateTestApp,
+  readJson,
+  SETUP_TOKEN,
+  startPostgres
+} from '@antasphere/chassis-server/testing';
+import { minimalTool } from '../host/minimal-tool.js';
+
+/**
+ * The `api.exportEntries` slot (PRDCT-2543): a tool adds named entries of rows
+ * to `GET /workspace/export`. This file carries its OWN two tools (the minimal
+ * test tool with the slot filled, and the same without it), so it proves the
+ * same thing under either runner of the suite: it never reads `@chassis-test/host`.
+ *
+ * The export bucket is 5 per user per 10 minutes: the filled tool's owner
+ * exports five times here, the bare tool's owner once. A request refused at
+ * the membership gate resolves no principal, so it spends the ADDRESS bucket
+ * only: those come from addresses of their own.
+ *
+ * EVERY export request of this file carries hostile values that name ANOTHER
+ * workspace (a header and a query parameter): the tool function receives the
+ * principal's resolved workspace id, never a raw request value (F2 of the
+ * PRDCT-2543 verification).
+ */
+
+const OWNER = {
+  email: 'owner@export-entries.test',
+  name: 'Export Owner',
+  password: 'export-owner-password-1'
+};
+const IP = '10.7.0.1';
+
+type MinimalTool = typeof minimalTool;
+
+/** What the filled tool contributes: each test sets it, the slot reads it per export. */
+let contribution: (db: Db, workspaceId: string) => Promise<ExportEntry[]> = async () => [];
+const seen: Array<{ workspaceId: string }> = [];
+
+const filledTool: MinimalTool = {
+  ...minimalTool,
+  api: {
+    ...minimalTool.api,
+    exportEntries: (domain) => {
+      // Bound once, with the tool's domain (the minimal tool's is empty).
+      expect(domain).toEqual({});
+      return (db, workspaceId) => {
+        seen.push({ workspaceId });
+        return contribution(db, workspaceId);
+      };
+    }
+  }
+} satisfies ToolDefinition<Record<never, never>, Record<string, never>>;
+
+const json = (body: unknown, headers: Record<string, string> = {}) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json', ...headers },
+  body: JSON.stringify(body)
+});
+
+const bootFilled = makeCreateTestApp((source?: NodeJS.ProcessEnv) => createPlatform(filledTool).boot(source));
+const bootBare = makeCreateTestApp((source?: NodeJS.ProcessEnv) => createPlatform(minimalTool).boot(source));
+type Booted = Awaited<ReturnType<typeof bootFilled>>;
+
+let container: StartedPostgreSqlContainer;
+let filled: Booted;
+let bare: Booted;
+
+async function claim(app: Booted): Promise<{ cookie: string; workspaceId: string }> {
+  const setup = await app.app.request(
+    '/api/v1/setup',
+    json({ setupToken: SETUP_TOKEN, instanceName: 'Export Entries', owner: OWNER })
+  );
+  expect(setup.status).toBe(201);
+  const signIn = await app.app.request(
+    '/api/v1/auth/sign-in/email',
+    json({ email: OWNER.email, password: OWNER.password }, { 'x-forwarded-for': IP })
+  );
+  expect(signIn.status).toBe(200);
+  const cookie = extractCookie(signIn);
+  const me = await readJson(await app.app.request('/api/v1/me', { headers: { cookie } }));
+  return { cookie, workspaceId: me.workspace.id as string };
+}
+
+async function upload(app: Booted, cookie: string, name: string, text: string): Promise<string> {
+  const res = await app.app.request(`/api/v1/files?name=${encodeURIComponent(name)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/octet-stream', cookie },
+    body: text
+  });
+  expect(res.status).toBe(201);
+  return (await readJson(res)).file.id as string;
+}
+
+/** A well-formed workspace id that is nobody's: what the hostile request values name. */
+const HOSTILE_WORKSPACE = '0b57113e-0000-4000-8000-00000000dead';
+
+const exportAs = (app: Booted, cookie: string, headers: Record<string, string> = {}) =>
+  app.app.request(
+    `/api/v1/workspace/export?workspaceId=${HOSTILE_WORKSPACE}&workspace=${HOSTILE_WORKSPACE}`,
+    {
+      headers: { cookie, 'x-forwarded-for': IP, 'x-export-workspace': HOSTILE_WORKSPACE, ...headers }
+    }
+  );
+
+async function exportAuditRows(app: Booted, cookie: string): Promise<number> {
+  const res = await app.app.request('/api/v1/audit?action=workspace.export', { headers: { cookie } });
+  expect(res.status).toBe(200);
+  const body = await readJson(res);
+  return (body.entries as Array<{ action: string }>).filter((e) => e.action === 'workspace.export').length;
+}
+
+let filledOwner: { cookie: string; workspaceId: string };
+let filledBlobId: string;
+
+beforeAll(async () => {
+  container = await startPostgres();
+  filled = await bootFilled(await createDatabase(container, 'export_entries_filled'));
+  bare = await bootBare(await createDatabase(container, 'export_entries_bare'));
+  filledOwner = await claim(filled);
+  filledBlobId = await upload(filled, filledOwner.cookie, 'kept.bin', 'a blob that stays');
+}, 240_000);
+
+afterAll(async () => {
+  await filled?.stop();
+  await bare?.stop();
+  await container?.stop();
+});
+
+describe('GET /workspace/export with the `api.exportEntries` slot filled', () => {
+  it('writes the tool entries after files.json and before the blobs, rows as JSON, hostile names sanitized', async () => {
+    contribution = async (db, workspaceId) => {
+      // The handle is a live one and the id is the caller's workspace.
+      const rows = await db
+        .select({ id: workspaces.id, name: workspaces.name })
+        .from(workspaces)
+        .where(eq(workspaces.id, workspaceId));
+      return [
+        { name: 'things', rows },
+        { name: '../../etc/cron.d/x', rows: [{ hostile: true }] },
+        { name: 'ctl\u0000\u001f\u007fname', rows: [] }
+      ];
+    };
+    const res = await exportAs(filled, filledOwner.cookie);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('application/zip');
+    const zip = new AdmZip(Buffer.from(await res.arrayBuffer()));
+    expect(zip.getEntries().map((e) => e.entryName)).toEqual([
+      'manifest.json',
+      'workspace.json',
+      'members.json',
+      'invitations.json',
+      'api-keys.json',
+      'projects.json',
+      'project_members.json',
+      'teams.json',
+      'team_members.json',
+      'project_teams.json',
+      'audit-log.ndjson',
+      'files.json',
+      'things.json',
+      '.._.._etc_cron.d_x.json',
+      'ctl___name.json',
+      `files/${filledBlobId}-kept.bin`,
+      'skipped-blobs.json'
+    ]);
+    expect(zip.readAsText('things.json')).toBe(
+      JSON.stringify([{ id: filledOwner.workspaceId, name: 'Export Entries' }], null, 2) + '\n'
+    );
+    expect(JSON.parse(zip.readAsText('.._.._etc_cron.d_x.json'))).toEqual([{ hostile: true }]);
+    expect(JSON.parse(zip.readAsText('ctl___name.json'))).toEqual([]);
+    // The manifest does not list the tool's entries.
+    expect(Object.keys(JSON.parse(zip.readAsText('manifest.json')))).toEqual([
+      'formatVersion',
+      'exportedAt',
+      'instance',
+      'workspaceId'
+    ]);
+    expect(seen.at(-1)).toEqual({ workspaceId: filledOwner.workspaceId });
+    expect(await exportAuditRows(filled, filledOwner.cookie)).toBe(1);
+  });
+
+  it('an empty list writes nothing: the entry list is the bare one', async () => {
+    contribution = async () => [];
+    const res = await exportAs(filled, filledOwner.cookie);
+    expect(res.status).toBe(200);
+    const zip = new AdmZip(Buffer.from(await res.arrayBuffer()));
+    expect(zip.getEntries().map((e) => e.entryName)).toEqual([
+      'manifest.json',
+      'workspace.json',
+      'members.json',
+      'invitations.json',
+      'api-keys.json',
+      'projects.json',
+      'project_members.json',
+      'teams.json',
+      'team_members.json',
+      'project_teams.json',
+      'audit-log.ndjson',
+      'files.json',
+      `files/${filledBlobId}-kept.bin`,
+      'skipped-blobs.json'
+    ]);
+    expect(await exportAuditRows(filled, filledOwner.cookie)).toBe(2);
+  });
+
+  it('a name that collides with a chassis entry answers 500, no zip, no audit row', async () => {
+    contribution = async () => [{ name: 'files', rows: [{ overwrite: true }] }];
+    const res = await exportAs(filled, filledOwner.cookie);
+    expect(res.status).toBe(500);
+    expect(res.headers.get('content-type')).toMatch(/json/);
+    expect(res.headers.get('content-disposition')).toBeNull();
+    const body = await readJson(res);
+    expect(JSON.stringify(body)).not.toContain('already an entry');
+    expect(await exportAuditRows(filled, filledOwner.cookie)).toBe(2);
+  });
+
+  it('a contribution that throws answers 500, no zip, no audit row', async () => {
+    contribution = async () => {
+      throw new Error('the tool could not read its rows');
+    };
+    const calls = seen.length;
+    const res = await exportAs(filled, filledOwner.cookie);
+    expect(seen.length).toBe(calls + 1);
+    expect(res.status).toBe(500);
+    expect(res.headers.get('content-type')).toMatch(/json/);
+    expect(res.headers.get('content-disposition')).toBeNull();
+    expect(await exportAuditRows(filled, filledOwner.cookie)).toBe(2);
+  });
+});
+
+describe("the workspace id the tool function receives is the principal's, never a request value", () => {
+  it('the hostile header and query parameters were sent on every export above, and never seen', () => {
+    expect(seen.length).toBeGreaterThanOrEqual(4);
+    expect(seen.map((s) => s.workspaceId)).toEqual(seen.map(() => filledOwner.workspaceId));
+  });
+
+  it('X-Workspace-Id naming a workspace the caller is NOT a member of: 401, the tool function is not called', async () => {
+    // A real workspace of the same instance, with no membership row for the caller.
+    const foreign = await filled.db.pool.query<{ id: string }>(
+      `INSERT INTO workspaces (name) VALUES ('Somebody else''s') RETURNING id`
+    );
+    const foreignId = foreign.rows[0]!.id;
+    contribution = async () => [{ name: 'things', rows: [] }];
+    const calls = seen.length;
+    for (const [selector, ip] of [
+      [foreignId, '10.7.0.2'],
+      [HOSTILE_WORKSPACE, '10.7.0.3']
+    ] as const) {
+      // Same answer for a workspace that exists and one that does not (no oracle).
+      const res = await exportAs(filled, filledOwner.cookie, {
+        'x-workspace-id': selector,
+        'x-forwarded-for': ip
+      });
+      expect(res.status).toBe(401);
+      expect(res.headers.get('content-type')).toMatch(/json/);
+      expect(res.headers.get('content-disposition')).toBeNull();
+    }
+    expect(seen.length).toBe(calls);
+    expect(await exportAuditRows(filled, filledOwner.cookie)).toBe(2);
+  });
+
+  it('X-Workspace-Id naming the OTHER workspace the caller is a member of: the tool receives that resolved id', async () => {
+    const created = await filled.app.request(
+      '/api/v1/workspaces',
+      json({ name: 'Second' }, { cookie: filledOwner.cookie, 'x-forwarded-for': IP })
+    );
+    expect(created.status).toBe(201);
+    const secondId = (await readJson(created)).workspace.id as string;
+    expect(secondId).not.toBe(filledOwner.workspaceId);
+
+    contribution = async (_db, workspaceId) => [{ name: 'things', rows: [{ workspaceId }] }];
+    const calls = seen.length;
+    const res = await exportAs(filled, filledOwner.cookie, {
+      'x-workspace-id': secondId,
+      'x-forwarded-for': '10.7.0.4'
+    });
+    expect(res.status).toBe(200);
+    expect(seen.length).toBe(calls + 1);
+    // The principal resolved to the second workspace: exactly that id, not the
+    // default one, and not the hostile header/query value riding the same request.
+    expect(seen.at(-1)).toEqual({ workspaceId: secondId });
+    const zip = new AdmZip(Buffer.from(await res.arrayBuffer()));
+    expect(JSON.parse(zip.readAsText('things.json'))).toEqual([{ workspaceId: secondId }]);
+    expect(JSON.parse(zip.readAsText('manifest.json')).workspaceId).toBe(secondId);
+  });
+});
+
+describe('GET /workspace/export with the slot ABSENT', () => {
+  it("the bundle's entry list is exactly the chassis sections and the blobs", async () => {
+    const owner = await claim(bare);
+    const blobId = await upload(bare, owner.cookie, 'kept.bin', 'a blob that stays');
+    const res = await exportAs(bare, owner.cookie);
+    expect(res.status).toBe(200);
+    const zip = new AdmZip(Buffer.from(await res.arrayBuffer()));
+    expect(zip.getEntries().map((e) => e.entryName)).toEqual([
+      'manifest.json',
+      'workspace.json',
+      'members.json',
+      'invitations.json',
+      'api-keys.json',
+      'projects.json',
+      'project_members.json',
+      'teams.json',
+      'team_members.json',
+      'project_teams.json',
+      'audit-log.ndjson',
+      'files.json',
+      `files/${blobId}-kept.bin`,
+      'skipped-blobs.json'
+    ]);
+    expect(await exportAuditRows(bare, owner.cookie)).toBe(1);
+  });
+});

package/test/integration/files.test.ts

@@ -0,0 +1,320 @@
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import { GenericContainer, type StartedTestContainer, Wait } from 'testcontainers';
+import {
+  createDatabase,
+  createTestApp,
+  extractCookie,
+  readJson,
+  startPostgres,
+  type TestApp,
+  host
+} from './helpers.js';
+
+/**
+ * Files module end-to-end (exit criterion 10): streamed upload, Range/206
+ * download, safe-serving headers — against the local driver, then the same
+ * core flow against MinIO through the s3 driver.
+ */
+
+const OWNER = { email: 'owner@files.test', name: 'Files Owner', password: 'files-owner-password-1' };
+const PAYLOAD = 'The quick brown fox jumps over the lazy dog'; // 43 bytes
+
+let container: StartedPostgreSqlContainer;
+
+const json = (body: unknown) => ({
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(body)
+});
+
+async function setupApp(app: TestApp): Promise<string> {
+  await app.app.request(
+    '/api/v1/setup',
+    json({ setupToken: 'integration-test-setup-token', instanceName: 'Files', owner: OWNER })
+  );
+  const signIn = await app.app.request(
+    '/api/v1/auth/sign-in/email',
+    json({ email: OWNER.email, password: OWNER.password })
+  );
+  return extractCookie(signIn);
+}
+
+async function uploadText(app: TestApp, cookie: string, name: string, text: string, contentType: string) {
+  return app.app.request(`/api/v1/files?name=${encodeURIComponent(name)}`, {
+    method: 'POST',
+    headers: { 'content-type': contentType, cookie },
+    body: text
+  });
+}
+
+beforeAll(async () => {
+  container = await startPostgres();
+});
+
+afterAll(async () => {
+  await container?.stop();
+});
+
+describe('local driver', () => {
+  let app: TestApp;
+  let cookie: string;
+  let fileId: string;
+
+  beforeAll(async () => {
+    app = await createTestApp(await createDatabase(container, 'files_local'), { MAX_FILE_SIZE_MB: '1' });
+    cookie = await setupApp(app);
+  });
+
+  afterAll(async () => {
+    await app?.stop();
+  });
+
+  it('uploads streamed bytes and returns the content address', async () => {
+    const res = await uploadText(app, cookie, 'fox.txt', PAYLOAD, 'text/plain');
+    expect(res.status).toBe(201);
+    const body = await readJson(res);
+    expect(body.file.sha256).toMatch(/^[a-f0-9]{64}$/);
+    expect(body.file.sizeBytes).toBe(43);
+    expect(body.deduplicated).toBe(false);
+    fileId = body.file.id;
+  });
+
+  it('re-uploading identical bytes deduplicates to the same row', async () => {
+    const res = await uploadText(app, cookie, 'fox-again.txt', PAYLOAD, 'text/plain');
+    expect(res.status).toBe(201);
+    const body = await readJson(res);
+    expect(body.deduplicated).toBe(true);
+    expect(body.file.id).toBe(fileId);
+  });
+
+  it('downloads in full with immutable caching and nosniff', async () => {
+    const res = await app.app.request(`/api/v1/files/${fileId}/content`, { headers: { cookie } });
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe(PAYLOAD);
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+    expect(res.headers.get('cache-control')).toContain('immutable');
+    expect(res.headers.get('accept-ranges')).toBe('bytes');
+    expect(res.headers.get('content-disposition')).toMatch(/^inline/); // text/plain is passive
+  });
+
+  it('serves an exact 206 slice with Content-Range (exit criterion 10)', async () => {
+    const res = await app.app.request(`/api/v1/files/${fileId}/content`, {
+      headers: { cookie, range: 'bytes=4-8' }
+    });
+    expect(res.status).toBe(206);
+    expect(await res.text()).toBe('quick');
+    expect(res.headers.get('content-range')).toBe('bytes 4-8/43');
+    expect(res.headers.get('content-length')).toBe('5');
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+  });
+
+  it('suffix and open ranges work (video-seek shapes)', async () => {
+    const tail = await app.app.request(`/api/v1/files/${fileId}/content`, {
+      headers: { cookie, range: 'bytes=-3' }
+    });
+    expect(tail.status).toBe(206);
+    expect(await tail.text()).toBe('dog');
+
+    const open = await app.app.request(`/api/v1/files/${fileId}/content`, {
+      headers: { cookie, range: 'bytes=40-' }
+    });
+    expect(open.status).toBe(206);
+    expect(await open.text()).toBe('dog');
+  });
+
+  it('rejects unsatisfiable and multi-range with 416 + bytes */size', async () => {
+    for (const range of ['bytes=100-', 'bytes=0-1,5-9']) {
+      const res = await app.app.request(`/api/v1/files/${fileId}/content`, {
+        headers: { cookie, range }
+      });
+      expect(res.status).toBe(416);
+      expect(res.headers.get('content-range')).toBe('bytes */43');
+    }
+  });
+
+  it('answers HEAD with headers and no body', async () => {
+    const res = await app.app.request(`/api/v1/files/${fileId}/content`, {
+      method: 'HEAD',
+      headers: { cookie }
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-length')).toBe('43');
+    expect(await res.text()).toBe('');
+  });
+
+  it('serves 304 on a matching ETag (content-addressed: hash is the tag)', async () => {
+    const first = await app.app.request(`/api/v1/files/${fileId}/content`, { headers: { cookie } });
+    const etag = first.headers.get('etag')!;
+    const res = await app.app.request(`/api/v1/files/${fileId}/content`, {
+      headers: { cookie, 'if-none-match': etag }
+    });
+    expect(res.status).toBe(304);
+  });
+
+  it('forces attachment for browser-renderable uploads (html)', async () => {
+    const up = await uploadText(app, cookie, 'evil.html', '<script>alert(1)</script>', 'text/html');
+    const body = await readJson(up);
+    const res = await app.app.request(`/api/v1/files/${body.file.id}/content`, { headers: { cookie } });
+    expect(res.headers.get('content-disposition')).toMatch(/^attachment/);
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+  });
+
+  it('enforces the size cap mid-stream with 413', async () => {
+    // Test app runs with MAX_FILE_SIZE_MB=1; send ~1.5MB without content-length honesty.
+    const big = 'x'.repeat(1_500_000);
+    const res = await uploadText(app, cookie, 'big.bin', big, 'application/octet-stream');
+    expect(res.status).toBe(413);
+  });
+
+  it('scopes machine access: a read-scope key can stream, cannot upload', async () => {
+    const mint = await app.app.request('/api/v1/api-keys', {
+      ...json({ name: 'files-ro', scopes: [host.scopes.read] }),
+      headers: { 'content-type': 'application/json', cookie }
+    });
+    const { key } = await readJson(mint);
+
+    const read = await app.app.request(`/api/v1/files/${fileId}/content`, {
+      headers: { authorization: `Bearer ${key}` }
+    });
+    expect(read.status).toBe(200);
+
+    const write = await app.app.request('/api/v1/files?name=x.txt', {
+      method: 'POST',
+      headers: { 'content-type': 'text/plain', authorization: `Bearer ${key}` },
+      body: 'nope'
+    });
+    expect(write.status).toBe(403);
+  });
+
+  it('delete removes metadata and the blob', async () => {
+    const up = await uploadText(app, cookie, 'temp.txt', 'delete me', 'text/plain');
+    const { file } = await readJson(up);
+    const del = await app.app.request(`/api/v1/files/${file.id}`, {
+      method: 'DELETE',
+      headers: { cookie }
+    });
+    expect(del.status).toBe(200);
+    const gone = await app.app.request(`/api/v1/files/${file.id}/content`, { headers: { cookie } });
+    expect(gone.status).toBe(404);
+  });
+
+  it('answers a clean 404 when the metadata row exists but the blob is unreachable (never a truncated 200)', async () => {
+    // The cross-replica local-storage situation (scale drill, I2): the shared
+    // Postgres row exists, but THIS replica's private disk has no blob.
+    // Simulated by deleting the blob file underneath a live row.
+    const up = await uploadText(
+      app,
+      cookie,
+      'ghost.txt',
+      'bytes that vanish from this replica',
+      'text/plain'
+    );
+    const { file } = await readJson(up);
+    const { rows } = await app.db.pool.query<{ workspace_id: string }>(
+      'SELECT workspace_id FROM files WHERE id = $1',
+      [file.id]
+    );
+    const blobPath = join(
+      app.env.DATA_DIR,
+      'storage',
+      'blobs',
+      'ws',
+      rows[0]!.workspace_id,
+      file.sha256.slice(0, 2),
+      file.sha256
+    );
+    await rm(blobPath);
+
+    // GET: a clean pre-body 404 with the error envelope — not 200 + headers
+    // followed by a dead stream (the silent truncation the drill surfaced).
+    const res = await app.app.request(`/api/v1/files/${file.id}/content`, { headers: { cookie } });
+    expect(res.status).toBe(404);
+    const body = await readJson(res);
+    expect(body.error.code).toBe('not_found');
+
+    // HEAD and Range take the same guard: no 2xx may promise unreachable bytes.
+    const head = await app.app.request(`/api/v1/files/${file.id}/content`, {
+      method: 'HEAD',
+      headers: { cookie }
+    });
+    expect(head.status).toBe(404);
+    const ranged = await app.app.request(`/api/v1/files/${file.id}/content`, {
+      headers: { cookie, range: 'bytes=0-4' }
+    });
+    expect(ranged.status).toBe(404);
+
+    // The metadata endpoint still serves the row — only the content is 404.
+    const meta = await app.app.request(`/api/v1/files/${file.id}`, { headers: { cookie } });
+    expect(meta.status).toBe(200);
+  });
+});
+
+describe('s3 driver (MinIO)', () => {
+  let minio: StartedTestContainer;
+  let app: TestApp;
+  let cookie: string;
+
+  beforeAll(async () => {
+    // MinIO no longer publishes images anonymously: Docker Hub's `minio/minio`
+    // answers "pull access denied" and quay.io/minio/minio answers 401 to any
+    // client without credentials (the GitHub runner's case; a Mac with the
+    // image cached never pulls). Bitnami's frozen legacy build of MinIO is
+    // still public; pinned on its multi-arch digest so the reference cannot
+    // move. Its entrypoint starts the server itself (no command), and the
+    // readiness probe waits past the entrypoint's own setup restart.
+    minio = await new GenericContainer(
+      'bitnamilegacy/minio:2025.7.23-debian-12-r5@sha256:6dabb4a2088c9a79908de3bc05f4586c23ad2182c8908e7e3acbf61c1467fb20'
+    )
+      .withEnvironment({ MINIO_ROOT_USER: 'minioadmin', MINIO_ROOT_PASSWORD: 'minioadmin' })
+      .withExposedPorts(9000)
+      .withWaitStrategy(Wait.forHttp('/minio/health/ready', 9000))
+      .start();
+
+    const endpoint = `http://${minio.getHost()}:${minio.getMappedPort(9000)}`;
+    // Create the bucket via the S3 API directly.
+    const { S3Client, CreateBucketCommand } = await import('@aws-sdk/client-s3');
+    const client = new S3Client({
+      region: 'us-east-1',
+      endpoint,
+      forcePathStyle: true,
+      credentials: { accessKeyId: 'minioadmin', secretAccessKey: 'minioadmin' }
+    });
+    await client.send(new CreateBucketCommand({ Bucket: 'chassis-test' }));
+
+    app = await createTestApp(await createDatabase(container, 'files_s3'), {
+      STORAGE_DRIVER: 's3',
+      S3_BUCKET: 'chassis-test',
+      S3_REGION: 'us-east-1',
+      S3_ENDPOINT: endpoint,
+      S3_ACCESS_KEY_ID: 'minioadmin',
+      S3_SECRET_ACCESS_KEY: 'minioadmin',
+      S3_FORCE_PATH_STYLE: 'true'
+    });
+    cookie = await setupApp(app);
+  }, 240_000);
+
+  afterAll(async () => {
+    await app?.stop();
+    await minio?.stop();
+  });
+
+  it('uploads and Range-streams through MinIO identically', async () => {
+    const up = await uploadText(app, cookie, 'fox-s3.txt', PAYLOAD, 'text/plain');
+    expect(up.status).toBe(201);
+    const { file } = await readJson(up);
+
+    const res = await app.app.request(`/api/v1/files/${file.id}/content`, {
+      headers: { cookie, range: 'bytes=4-8' }
+    });
+    expect(res.status).toBe(206);
+    expect(await res.text()).toBe('quick');
+    expect(res.headers.get('content-range')).toBe('bytes 4-8/43');
+
+    const full = await app.app.request(`/api/v1/files/${file.id}/content`, { headers: { cookie } });
+    expect(full.status).toBe(200);
+    expect(await full.text()).toBe(PAYLOAD);
+  });
+});