cursedbelt-server 1.0.0

package/src/server/storage/files/chunkedUpload.spec.ts

@@ -0,0 +1,111 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaCtx } from '../types';
+import { catalogueUploadKey, createSqliteFileCatalogue } from './catalogue';
+import { createChunkedUploadService } from './chunkedUpload';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import { createStorageOpsLedger } from './storageOps';
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 'u1' };
+
+describe('chunked upload', () => {
+  let db: Database;
+  let root: string;
+  let clock = 0;
+
+  beforeEach(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-chunk-'));
+    clock = 0;
+  });
+  afterEach(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const build = () => {
+    const store = createDiskStore(root);
+    const catalogue = createSqliteFileCatalogue({
+      db,
+      store,
+      workDir: path.join(root, 'w'),
+      owner: (c) => c.userId,
+      now: () => ++clock,
+    });
+    const ledger = createStorageOpsLedger(db, () => ++clock);
+    const minted: Array<{ key: string; sid: string; ci: number; tc: number }> = [];
+    const svc = createChunkedUploadService({
+      catalogue,
+      ledger,
+      backend: 'binary',
+      chunkSize: 8 * 1024 * 1024,
+      owner: (c) => c.userId,
+      now: () => ++clock,
+      mintChunkUpload: async (a) => {
+        minted.push(a);
+        return `https://bs.example/upload-chunk/app/${a.key}?sid=${a.sid}&ci=${a.ci}&tc=${a.tc}`;
+      },
+    });
+    return { catalogue, ledger, svc, minted };
+  };
+
+  test('init reserves a file, records a pending upload op, and mints one URL per chunk', async () => {
+    const { ledger, svc, minted } = build();
+    // 20 MiB at an 8 MiB chunk size ⇒ 3 chunks.
+    const init = await svc.init(CTX, {
+      name: 'big.png',
+      mime: 'image/png',
+      size: 20 * 1024 * 1024,
+    });
+    expect(init.chunkCount).toBe(3);
+    expect(init.chunkUploadUrls).toHaveLength(3);
+    expect(minted.map((m) => m.ci)).toEqual([0, 1, 2]);
+    expect(minted.every((m) => m.tc === 3 && m.sid === init.sid)).toBe(true);
+    // The mint targets exactly the key the catalogue will look for on complete.
+    expect(init.key).toBe(catalogueUploadKey('u1', init.fileId, 'image/png'));
+
+    // A durable pending 'upload' op keyed by the session id.
+    const op = ledger.get(init.sid);
+    expect(op?.status).toBe('pending');
+    expect(op?.action).toBe('upload');
+    expect(op?.key).toBe(init.key);
+    expect(svc.pending()).toBe(1);
+  });
+
+  test('complete registers the catalogue row over the assembled bytes + marks the op done', async () => {
+    const { catalogue, ledger, svc } = build();
+    const init = await svc.init(CTX, {
+      name: 'photo.png',
+      mime: 'image/png',
+      size: 12 * 1024 * 1024,
+      tags: ['big'],
+    });
+
+    const rec = await svc.complete(init.sid, { size: 12 * 1024 * 1024 });
+    expect(rec?.id).toBe(init.fileId);
+    expect(rec?.name).toBe('photo.png');
+    expect(rec?.tags).toEqual(['big']);
+    // Now discoverable through the normal catalogue (no re-upload happened).
+    expect((await catalogue.get(CTX, init.fileId))?.name).toBe('photo.png');
+    expect(ledger.get(init.sid)?.status).toBe('done');
+    expect(svc.pending()).toBe(0);
+
+    // A second complete for the same (now-cleared) session is a no-op.
+    expect(await svc.complete(init.sid)).toBeNull();
+  });
+
+  test('abort marks the op failed and drops the session (no catalogue row)', async () => {
+    const { catalogue, ledger, svc } = build();
+    const init = await svc.init(CTX, { name: 'x.png', mime: 'image/png', size: 1 });
+    svc.abort(init.sid);
+    expect(ledger.get(init.sid)?.status).toBe('failed');
+    expect(svc.pending()).toBe(0);
+    expect(await catalogue.get(CTX, init.fileId)).toBeNull();
+  });
+});

package/src/server/storage/files/chunkedUpload.ts

@@ -0,0 +1,146 @@
+import { DEFAULT_UPLOAD_CHUNK_SIZE } from 'cursedbelt-core/media/upload-limits';
+import type { MediaCtx } from '../types';
+import { catalogueUploadKey } from './catalogue';
+import type { StorageOpsLedger } from './storageOps';
+import type { FileCatalogue, FileRecord } from './types';
+
+// ── Chunked upload (large files, direct-to-backend) ──────────────────────────────
+// For multi-GB uploads we don't proxy bytes through the app origin. Instead: the client asks the
+// app to START an upload (init) → the app mints per-chunk PUT URLs that go DIRECT to the byte
+// backend (binary-server), records a durable `upload` ledger op, and hands the URLs back. The
+// client PUTs each chunk to the backend, which assembles them at the target key once the last
+// arrives. Then the client (or a backend webhook) calls COMPLETE, and the app registers the
+// catalogue row over the already-stored bytes (no re-upload) + kicks processing.
+//
+// This module is backend-AGNOSTIC: the app injects `mintChunkUpload` (the binary-server chunk URL
+// + signed sid/ci/tc token). On disk-only deploys, an app simply doesn't wire chunked uploads and
+// keeps the streamed `PUT /upload`. Sessions are in-memory (the transient name/mime/size); the
+// ledger row is the DURABLE record of intent, so an abandoned upload is observable/reconcilable.
+
+const DEFAULT_CHUNK_SIZE = DEFAULT_UPLOAD_CHUNK_SIZE;
+
+export type ChunkedInit = {
+  fileId: string;
+  /** Chunk session id — also the ledger op id; echoed to the backend as sid so its assemble event
+   * matches our storage_operations row. */
+  sid: string;
+  /** The storage key the assembled bytes land at (fsSourceKey for video, else fileBinaryKey). */
+  key: string;
+  chunkSize: number;
+  chunkCount: number;
+  /** One direct-to-backend PUT URL per chunk, in index order. */
+  chunkUploadUrls: string[];
+};
+
+type Session = {
+  fileId: string;
+  owner: string;
+  ctx: MediaCtx;
+  name: string;
+  mime: string;
+  size: number;
+  key: string;
+  chunkCount: number;
+  tags?: string[];
+  createdAt: number;
+};
+
+export interface ChunkedUploadService {
+  /** Begin a chunked upload: reserve an id, record a pending `upload` op, and mint the per-chunk
+   * direct-to-backend PUT URLs. */
+  init(
+    ctx: MediaCtx,
+    req: { name: string; mime: string; size: number; tags?: string[] },
+  ): Promise<ChunkedInit>;
+  /** Finish it: mark the op done and register the catalogue row over the assembled bytes. Returns
+   * the new record, or null if the session is unknown (already completed / server restarted). */
+  complete(sid: string, confirmed?: { size?: number }): Promise<FileRecord | null>;
+  /** Give up on a session (client cancelled / a chunk failed) — mark the ledger op failed. */
+  abort(sid: string): void;
+  /** Open session count (observability / tests). */
+  pending(): number;
+}
+
+/**
+ * Mint the direct-to-backend PUT URL for one chunk. The app supplies this so the module stays
+ * backend-agnostic. For binary-server: `${base}/upload-chunk/${app}/${key}?token=` with a token
+ * carrying { k, uid, sid, ci, tc }.
+ */
+export type MintChunkUpload = (args: {
+  key: string;
+  sid: string;
+  ci: number;
+  tc: number;
+  owner: string;
+}) => Promise<string>;
+
+export function createChunkedUploadService(cfg: {
+  catalogue: FileCatalogue;
+  ledger: StorageOpsLedger;
+  /** Byte backend label recorded on the ledger op (e.g. 'binary'). */
+  backend: string;
+  mintChunkUpload: MintChunkUpload;
+  chunkSize?: number;
+  owner?: (ctx: MediaCtx) => string;
+  now?: () => number;
+}): ChunkedUploadService {
+  const ownerOf = cfg.owner ?? ((c: MediaCtx) => c.tenantId);
+  const now = cfg.now ?? (() => Date.now());
+  const chunkSize = cfg.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  const sessions = new Map<string, Session>();
+
+  return {
+    async init(ctx, req) {
+      const owner = ownerOf(ctx);
+      const fileId = crypto.randomUUID();
+      const sid = crypto.randomUUID();
+      const key = catalogueUploadKey(owner, fileId, req.mime);
+      const chunkCount = Math.max(1, Math.ceil((req.size || 1) / chunkSize));
+      // Durable record of intent — its op_id (sid) is what the backend echoes on assemble.
+      cfg.ledger.record({ owner, fileId, action: 'upload', key, backend: cfg.backend, opId: sid });
+      sessions.set(sid, {
+        fileId,
+        owner,
+        ctx,
+        name: req.name,
+        mime: req.mime,
+        size: req.size,
+        key,
+        chunkCount,
+        tags: req.tags,
+        createdAt: now(),
+      });
+      const chunkUploadUrls = await Promise.all(
+        Array.from({ length: chunkCount }, (_, ci) =>
+          cfg.mintChunkUpload({ key, sid, ci, tc: chunkCount, owner }),
+        ),
+      );
+      return { fileId, sid, key, chunkSize, chunkCount, chunkUploadUrls };
+    },
+
+    async complete(sid, confirmed) {
+      const s = sessions.get(sid);
+      if (!s) return null;
+      cfg.ledger.markDone(sid);
+      const rec = await cfg.catalogue.registerUploaded(s.ctx, {
+        id: s.fileId,
+        name: s.name,
+        mime: s.mime,
+        size: confirmed?.size ?? s.size,
+        tags: s.tags,
+      });
+      sessions.delete(sid);
+      return rec;
+    },
+
+    abort(sid) {
+      if (!sessions.has(sid)) return;
+      cfg.ledger.markFailed(sid, 'aborted');
+      sessions.delete(sid);
+    },
+
+    pending() {
+      return sessions.size;
+    },
+  };
+}

package/src/server/storage/files/collections.spec.ts

@@ -0,0 +1,294 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaCtx } from '../types';
+import { createSqliteFileCatalogue } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue } from './types';
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 'owner1' };
+const CTX2: MediaCtx = { userId: 'u2', tenantId: 'owner2' };
+const stream = (s: string) =>
+  new Response(new TextEncoder().encode(s)).body as ReadableStream<Uint8Array>;
+
+describe('FileCatalogue — Collections', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue;
+  let clock = 2000;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-coll-'));
+    cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'work'),
+      now: () => ++clock,
+    });
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const ingest = (ctx: MediaCtx, name: string) =>
+    cat.ingest(ctx, { name, mime: 'image/png', body: stream(`bytes-${name}`) });
+
+  // ── CRUD ─────────────────────────────────────────────────────────────────────
+
+  test('createCollection and listCollections round-trip', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'Summer 2025' });
+    expect(coll.name).toBe('Summer 2025');
+    expect(coll.kind).toBe('custom');
+    expect(coll.visibility).toBe('normal');
+    expect(coll.fileCount).toBe(0);
+
+    const list = await cat.listCollections(CTX);
+    expect(list.some((c) => c.id === coll.id)).toBe(true);
+  });
+
+  test('createCollection trims name and rejects empty', async () => {
+    const c = await cat.createCollection(CTX, { name: '  Trip  ' });
+    expect(c.name).toBe('Trip');
+
+    await expect(cat.createCollection(CTX, { name: '   ' })).rejects.toThrow();
+  });
+
+  test('updateCollection renames and changes visibility', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'Before' });
+    const updated = await cat.updateCollection(CTX, coll.id, {
+      name: 'After',
+      visibility: 'unlock',
+    });
+    expect(updated?.name).toBe('After');
+    expect(updated?.visibility).toBe('unlock');
+    // updateCollection with no such id returns null
+    expect(await cat.updateCollection(CTX, 'nonexistent', { name: 'X' })).toBeNull();
+  });
+
+  test('removeCollection deletes collection but not files', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'ToDelete' });
+    const file = await ingest(CTX, 'willsurvive.png');
+    await cat.addToCollection(CTX, coll.id, [file.id]);
+
+    await cat.removeCollection(CTX, coll.id);
+
+    // Collection is gone
+    const list = await cat.listCollections(CTX);
+    expect(list.some((c) => c.id === coll.id)).toBe(false);
+    // File still exists
+    expect(await cat.get(CTX, file.id)).not.toBeNull();
+  });
+
+  test('removeCollection silently ignores nonexistent id', async () => {
+    await expect(cat.removeCollection(CTX, 'ghost-id')).resolves.toBeUndefined();
+  });
+
+  // ── Membership ───────────────────────────────────────────────────────────────
+
+  test('addToCollection / removeFromCollection are idempotent', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'Membership' });
+    const f1 = await ingest(CTX, 'f1.png');
+    const f2 = await ingest(CTX, 'f2.png');
+
+    // Add twice — should be idempotent
+    await cat.addToCollection(CTX, coll.id, [f1.id, f2.id]);
+    await cat.addToCollection(CTX, coll.id, [f1.id]);
+
+    const page = await cat.list(CTX, { collectionId: coll.id });
+    const ids = page.items.map((f) => f.id).sort();
+    expect(ids).toEqual([f1.id, f2.id].sort());
+
+    // Remove f1; f2 remains
+    await cat.removeFromCollection(CTX, coll.id, [f1.id]);
+    const after = await cat.list(CTX, { collectionId: coll.id });
+    expect(after.items.map((f) => f.id)).toEqual([f2.id]);
+  });
+
+  test('addToCollection ignores unknown or other-owner file ids', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'OwnerGuard' });
+    const other = await ingest(CTX2, 'other-owner.png');
+
+    // Should not throw and should not add the foreign file
+    await cat.addToCollection(CTX, coll.id, [other.id, 'completely-unknown']);
+    const page = await cat.list(CTX, { collectionId: coll.id });
+    expect(page.items).toHaveLength(0);
+  });
+
+  // ── collectionIds on FileRecord ───────────────────────────────────────────────
+
+  test('FileRecord.collectionIds reflects current memberships', async () => {
+    const c1 = await cat.createCollection(CTX, { name: 'C1' });
+    const c2 = await cat.createCollection(CTX, { name: 'C2' });
+    const file = await ingest(CTX, 'multi.png');
+
+    await cat.addToCollection(CTX, c1.id, [file.id]);
+    await cat.addToCollection(CTX, c2.id, [file.id]);
+
+    const rec = await cat.get(CTX, file.id);
+    expect(rec?.collectionIds.sort()).toEqual([c1.id, c2.id].sort());
+    expect(rec?.favorite).toBe(false);
+  });
+
+  // ── Favorites ────────────────────────────────────────────────────────────────
+
+  test('setFavorite lazily creates Favorites collection and toggles membership', async () => {
+    const file = await ingest(CTX, 'favfile.png');
+
+    // Not favorited initially
+    expect((await cat.get(CTX, file.id))?.favorite).toBe(false);
+
+    // Favorite it — Favorites collection should be created
+    await cat.setFavorite(CTX, file.id, true);
+    const rec = await cat.get(CTX, file.id);
+    expect(rec?.favorite).toBe(true);
+
+    const collections = await cat.listCollections(CTX);
+    const favColl = collections.find((c) => c.kind === 'favorites');
+    expect(favColl).toBeDefined();
+    expect(favColl?.name).toBe('Favorites');
+    expect(favColl?.fileCount).toBe(1);
+
+    // Unfavorite
+    await cat.setFavorite(CTX, file.id, false);
+    expect((await cat.get(CTX, file.id))?.favorite).toBe(false);
+  });
+
+  test('setFavorite is idempotent (toggle twice stays in correct state)', async () => {
+    const file = await ingest(CTX, 'idem.png');
+    await cat.setFavorite(CTX, file.id, true);
+    await cat.setFavorite(CTX, file.id, true); // idempotent
+    expect((await cat.get(CTX, file.id))?.favorite).toBe(true);
+    await cat.setFavorite(CTX, file.id, false);
+    await cat.setFavorite(CTX, file.id, false); // idempotent
+    expect((await cat.get(CTX, file.id))?.favorite).toBe(false);
+  });
+
+  test('Favorites collection is a singleton per owner', async () => {
+    const f1 = await ingest(CTX, 'sing1.png');
+    const f2 = await ingest(CTX, 'sing2.png');
+    await cat.setFavorite(CTX, f1.id, true);
+    await cat.setFavorite(CTX, f2.id, true);
+
+    const collections = await cat.listCollections(CTX);
+    expect(collections.filter((c) => c.kind === 'favorites')).toHaveLength(1);
+  });
+
+  test('favorite=true filter on list returns only favorited files', async () => {
+    // Create a clean ctx3 so we start fresh
+    const CTX3: MediaCtx = { userId: 'u3', tenantId: 'owner3' };
+    const a = await ingest(CTX3, 'favA.png');
+    const b = await ingest(CTX3, 'favB.png');
+    await ingest(CTX3, 'notFav.png');
+
+    await cat.setFavorite(CTX3, a.id, true);
+    await cat.setFavorite(CTX3, b.id, true);
+
+    const page = await cat.list(CTX3, { favorite: true });
+    const ids = page.items.map((f) => f.id).sort();
+    expect(ids).toEqual([a.id, b.id].sort());
+  });
+
+  test('favorite=true with no Favorites collection returns empty page', async () => {
+    const CTX4: MediaCtx = { userId: 'u4', tenantId: 'owner4' };
+    await ingest(CTX4, 'nofav.png');
+    const page = await cat.list(CTX4, { favorite: true });
+    expect(page.items).toHaveLength(0);
+  });
+
+  test('Favorites collection cannot be removed', async () => {
+    const f = await ingest(CTX, 'keepfav.png');
+    await cat.setFavorite(CTX, f.id, true);
+    const colls = await cat.listCollections(CTX);
+    const favColl = colls.find((c) => c.kind === 'favorites')!;
+    await expect(cat.removeCollection(CTX, favColl.id)).rejects.toThrow('Favorites');
+  });
+
+  // ── Unlock-gated visibility ───────────────────────────────────────────────────
+
+  test('unlock-gated collection excluded from listCollections by default', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'Secret', visibility: 'unlock' });
+
+    const defaultList = await cat.listCollections(CTX);
+    expect(defaultList.some((c) => c.id === coll.id)).toBe(false);
+
+    const fullList = await cat.listCollections(CTX, { includeUnlockable: true });
+    expect(fullList.some((c) => c.id === coll.id)).toBe(true);
+  });
+
+  test('list with unlock-gated collectionId returns empty unless includeUnlockable', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'Hidden', visibility: 'unlock' });
+    const file = await ingest(CTX, 'hidden.png');
+    await cat.addToCollection(CTX, coll.id, [file.id]);
+
+    const gated = await cat.list(CTX, { collectionId: coll.id });
+    expect(gated.items).toHaveLength(0);
+
+    const open = await cat.list(CTX, { collectionId: coll.id, includeUnlockable: true });
+    expect(open.items.some((f) => f.id === file.id)).toBe(true);
+  });
+
+  // ── Owner isolation ───────────────────────────────────────────────────────────
+
+  test('owner isolation: collections and memberships are tenant-scoped', async () => {
+    const collA = await cat.createCollection(CTX, { name: 'AOnly' });
+    const collB = await cat.createCollection(CTX2, { name: 'BOnly' });
+
+    const fileA = await ingest(CTX, 'a-file.png');
+    const fileB = await ingest(CTX2, 'b-file.png');
+    await cat.addToCollection(CTX, collA.id, [fileA.id]);
+    await cat.addToCollection(CTX2, collB.id, [fileB.id]);
+
+    // CTX can only see its own collections
+    const listA = await cat.listCollections(CTX);
+    expect(listA.some((c) => c.id === collB.id)).toBe(false);
+
+    // CTX cannot see files from collB
+    const pageA = await cat.list(CTX, { collectionId: collB.id });
+    expect(pageA.items).toHaveLength(0);
+
+    // CTX2 cannot see files from collA
+    const pageB = await cat.list(CTX2, { collectionId: collA.id });
+    expect(pageB.items).toHaveLength(0);
+  });
+
+  // ── Cascade on file remove ────────────────────────────────────────────────────
+
+  test('removing a file removes its collection memberships', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'CascadeTest' });
+    const file = await ingest(CTX, 'cascade.png');
+    await cat.addToCollection(CTX, coll.id, [file.id]);
+
+    // Confirm it's in there
+    const before = await cat.list(CTX, { collectionId: coll.id });
+    expect(before.items.some((f) => f.id === file.id)).toBe(true);
+
+    await cat.remove(CTX, file.id);
+
+    const after = await cat.list(CTX, { collectionId: coll.id });
+    expect(after.items.some((f) => f.id === file.id)).toBe(false);
+    // Collection itself still exists
+    const colls = await cat.listCollections(CTX);
+    expect(colls.some((c) => c.id === coll.id)).toBe(true);
+  });
+
+  test('removing a collection removes memberships but not files', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'CollCascade' });
+    const file = await ingest(CTX, 'survives.png');
+    await cat.addToCollection(CTX, coll.id, [file.id]);
+
+    await cat.removeCollection(CTX, coll.id);
+
+    // File survives
+    expect(await cat.get(CTX, file.id)).not.toBeNull();
+    // collectionIds no longer includes the removed collection
+    const rec = await cat.get(CTX, file.id);
+    expect(rec?.collectionIds.includes(coll.id)).toBe(false);
+  });
+});

package/src/server/storage/files/fileRoutes.replace.spec.ts

@@ -0,0 +1,88 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Hono } from 'hono';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import { createStreamTokenService } from '../streamToken';
+import type { MediaCtx, MediaStore } from '../types';
+import { createSqliteFileCatalogue, fileBinaryKey } from './catalogue';
+import { mountFileRoutes } from './fileRoutes';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue, PrivateFileCatalogue } from './types';
+
+// PUT /_files/replace/:id — the editor's "overwrite original" byte edge.
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+const streamToken = createStreamTokenService({ secret: 'stream' });
+const stream = (s: string) =>
+  new Response(new TextEncoder().encode(s)).body as ReadableStream<Uint8Array>;
+
+describe('fileRoutes — replace', () => {
+  let db: Database;
+  let root: string;
+  let store: MediaStore;
+  let cat: FileCatalogue & PrivateFileCatalogue;
+  let authed = true;
+  const app = new Hono();
+  let fileId: string;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fr-replace-'));
+    store = createDiskStore(root);
+    cat = createSqliteFileCatalogue({
+      db,
+      store,
+      workDir: path.join(root, 'w'),
+      owner: (c) => c.userId,
+    });
+    mountFileRoutes(app, {
+      store,
+      token: streamToken,
+      catalogue: cat,
+      authorizeUpload: () => (authed ? CTX : null),
+    });
+    fileId = (await cat.ingest(CTX, { name: 'doc.txt', mime: 'text/plain', body: stream('old') }))
+      .id;
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('replaces bytes under the same id', async () => {
+    const res = await app.request(`/_files/replace/${fileId}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'text/plain', 'x-filename': 'doc-v2.txt' },
+      body: 'brand new bytes',
+    });
+    expect(res.status).toBe(200);
+    const { file } = (await res.json()) as { file: { id: string; name: string; size: number } };
+    expect(file.id).toBe(fileId);
+    expect(file.name).toBe('doc-v2.txt');
+    const bytes = await store.get(fileBinaryKey(CTX.userId, fileId));
+    expect(new TextDecoder().decode(bytes as Uint8Array)).toBe('brand new bytes');
+  });
+
+  test('unknown id → 404; unauthorized → 401', async () => {
+    const missing = await app.request('/_files/replace/nope', {
+      method: 'PUT',
+      headers: { 'content-type': 'text/plain' },
+      body: 'x',
+    });
+    expect(missing.status).toBe(404);
+
+    authed = false;
+    const denied = await app.request(`/_files/replace/${fileId}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'text/plain' },
+      body: 'x',
+    });
+    expect(denied.status).toBe(401);
+    authed = true;
+  });
+});