@proteinjs/db-file 1.8.4 → 1.9.1

package/test/FileDerivedProvenance.test.ts

@@ -0,0 +1,248 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { SourceRepository } from '@proteinjs/reflection';
+import { UserAuth, UserRepo, User } from '@proteinjs/user';
+import { File, FileTable } from '../src/tables/FileTable';
+import { tables } from '../src/tables/tables';
+import { FileStorage } from '../src/FileStorage';
+import { FileStorageDriver } from '../src/FileStorageDriver';
+import { FileVariantKind } from '../src/FileVariantMaker';
+import { FileTestEnvironment } from './FileTestEnvironment';
+
+/**
+ * A derived File — a variant the seam makes (at ingest with the bytes in hand, or on the read
+ * path's first request) and the copy for others — carries its ORIGINAL's provenance: who made the
+ * bytes (`origin`, `originModel`), where they came from (`sourceUrl`, `sourcePageUrl`,
+ * `retrievedAt`) and the rights that ride with them (`license`, `licenseUrl`, `attribution`) —
+ * the columns the table itself names as provenance (`FileTable.provenanceColumns`). A rendition's
+ * provenance is its original's: a consumer that labels a thumbnail with what made it, or refuses a
+ * non-capture picture as evidence, reads the row it draws, without a join. The library that makes
+ * the row writes it, whichever door made the row; a row with no provenance derives rows with none
+ * (nothing is invented); a row derived from a derived row carries what that row carries — its
+ * original's. The facts of a row's OWN bytes (`size`, `contentHash`, the dimensions) stay the
+ * maker's answer, never the original's.
+ */
+
+const originalBytes = Buffer.concat([Buffer.from('ORIGINAL:'), Buffer.from(Array.from({ length: 64 }, (_, i) => i))]);
+/** What the copy-for-others maker takes off a copy (the location marker of the real one). */
+const COPY_MARK = Buffer.from('-FOR-OTHERS');
+
+/**
+ * Every provenance column populated at once — whatever the story, each is seen to travel. The
+ * fixture is tied to the table's list below: a provenance column added to the table must be added
+ * here, and is then proven to travel like the rest.
+ */
+const PROVENANCE = {
+  origin: 'generation',
+  originModel: 'vendor/picture-model-1',
+  sourceUrl: 'https://source.test/pictures/1.jpg',
+  sourcePageUrl: 'https://source.test/pages/1',
+  retrievedAt: new Date('2026-09-25T10:00:00.000Z'),
+  license: 'CC BY-SA 4.0',
+  licenseUrl: 'https://creativecommons.org/licenses/by-sa/4.0/',
+  attribution: 'Photo by Someone, CC BY-SA 4.0',
+};
+
+/** In-memory proxy-shape driver (no signed URLs) — the DbFileStorageDriver serving shape. */
+class ProxyDriver implements FileStorageDriver {
+  readonly store = new Map<string, Buffer>();
+
+  async createFile(file: File, fileData: string): Promise<void> {
+    this.store.set(file.id, Buffer.from(fileData, 'base64'));
+  }
+
+  async getFileData(fileId: string): Promise<string> {
+    const data = this.store.get(fileId);
+    if (data === undefined) {
+      throw new Error(`No such object: ${fileId}`);
+    }
+    return data.toString('base64');
+  }
+
+  async updateFileData(fileId: string, data: string): Promise<void> {
+    this.store.set(fileId, Buffer.from(data, 'base64'));
+  }
+
+  async deleteFile(fileId: string): Promise<void> {
+    this.store.delete(fileId);
+  }
+}
+
+const testEnv = new FileTestEnvironment();
+type UserAuthInternals = { userRepo?: unknown };
+type SourceRepositoryInternals = { objectCache: Record<string, unknown[]> };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+
+let owner: User;
+let recipient: User;
+const reachableFileIds = new Set<string>();
+
+/** The stub variant maker: a picture's `preview` and `stage` — bytes marked with the kind, a type, dimensions. Keeps the copy mark on (the real one keeps a picture's tags for its owner). */
+const registerVariantMaker = () => {
+  objectCache()['@proteinjs/db-file/FileVariantMaker'] = [
+    {
+      appliesTo: (file: File) => file.type.startsWith('image/'),
+      make: async (file: File, bytes: Buffer, kind: FileVariantKind) => ({
+        bytes: Buffer.concat([Buffer.from(`${kind.toUpperCase()}:`), bytes.subarray(0, 8), COPY_MARK]),
+        type: 'image/webp',
+        width: kind === 'stage' ? 1600 : 512,
+        height: kind === 'stage' ? 800 : 256,
+      }),
+    },
+  ];
+};
+
+/** The stub copy maker: a picture's copy is its bytes with the mark taken off. */
+const registerCopyMaker = () => {
+  objectCache()['@proteinjs/db-file/FileCopyForOthers'] = [
+    {
+      appliesTo: (file: File) => file.type.startsWith('image/'),
+      make: async (file: File, bytes: Buffer) => bytes.subarray(0, bytes.length - COPY_MARK.length),
+    },
+  ];
+};
+
+beforeAll(async () => {
+  await testEnv.beforeAll();
+  objectCache()['@proteinjs/user-auth/AuthenticatedUserRepo'] = [new UserRepo()];
+  (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+  objectCache()['@proteinjs/db-file/FileReachabilityResolver'] = [
+    // The content leg vouches for the recipient alone (a share they accepted).
+    {
+      canReadViaReference: async (fileId: string) =>
+        reachableFileIds.has(fileId) && new UserRepo().getUser().id === recipient.id,
+    },
+  ];
+  owner = await testEnv.createUser({ name: 'File owner', email: 'provenance-owner@test.local' });
+  recipient = await testEnv.createUser({ name: 'Share recipient', email: 'provenance-recipient@test.local' });
+  testEnv.actAs(owner);
+});
+
+afterAll(async () => {
+  delete objectCache()['@proteinjs/db-file/FileReachabilityResolver'];
+  delete objectCache()['@proteinjs/db-file/FileVariantMaker'];
+  delete objectCache()['@proteinjs/db-file/FileCopyForOthers'];
+  (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+  await testEnv.afterAll();
+});
+
+const driver = new ProxyDriver();
+
+beforeEach(() => {
+  reachableFileIds.clear();
+  registerVariantMaker();
+  registerCopyMaker();
+  testEnv.setDriver(driver);
+  testEnv.actAs(owner);
+});
+
+/** A picture of the owner's, with (or without) its provenance, stored with no variant. */
+const createOwnerPicture = async (name: string, provenance: Partial<File> = {}): Promise<File> =>
+  await new FileStorage().createFile(
+    {
+      name,
+      type: 'image/jpeg',
+      size: originalBytes.length,
+      width: 4032,
+      height: 3024,
+      contentHash: 'a'.repeat(64),
+      ...provenance,
+    } as File,
+    Buffer.concat([originalBytes, COPY_MARK]).toString('base64')
+  );
+
+const rowAsSystem = async (fileId: string): Promise<File> => (await getDbAsSystem().get(tables.File, { id: fileId }))!;
+
+/** The provenance a row carries, column for column as the table names them — `null` for a column it does not hold. */
+const provenanceOf = (row: File): Record<string, unknown> =>
+  FileTable.provenanceColumns.reduce<Record<string, unknown>>(
+    (carried, column) => ({ ...carried, [column]: row[column] ?? null }),
+    {}
+  );
+
+const NO_PROVENANCE = provenanceOf({} as File);
+
+/** The copy for others of a file, made by a recipient's read of its bytes. */
+const copyForOthersOf = async (file: File): Promise<File> => {
+  reachableFileIds.add(file.id);
+  testEnv.actAs(recipient);
+  await new FileStorage().getFileData(file.id);
+  testEnv.actAs(owner);
+  const copyId = (await rowAsSystem(file.id)).copyForOthers?._id;
+  expect(copyId).toBeTruthy();
+  return await rowAsSystem(copyId!);
+};
+
+describe('the list is the table’s own', () => {
+  it('names the producer, the web source and the rights record — and the fixture covers every column it names, so a column added there is proven to travel', () => {
+    expect([...FileTable.provenanceColumns].sort()).toEqual(Object.keys(PROVENANCE).sort());
+    expect(FileTable.provenanceColumns).toEqual(expect.arrayContaining(['origin', 'originModel']));
+    // The facts of a row's own bytes are not provenance.
+    expect(FileTable.provenanceColumns).not.toEqual(expect.arrayContaining(['contentHash']));
+    expect(FileTable.provenanceColumns).not.toEqual(expect.arrayContaining(['size']));
+  });
+});
+
+describe('a derived row carries its original’s provenance', () => {
+  it("the ingest door: every variant deriveVariants makes carries the original's provenance, column for column; the maker's own answer (bytes, type, dimensions) stays its own", async () => {
+    const file = await createOwnerPicture('made.jpg', PROVENANCE);
+
+    const { variants } = await new FileStorage().deriveVariants(file, Buffer.concat([originalBytes, COPY_MARK]));
+
+    expect(Object.keys(variants).sort()).toEqual(['preview', 'stage']);
+    for (const kind of ['preview', 'stage'] as const) {
+      const variant = await rowAsSystem(variants[kind]!.id);
+      expect(provenanceOf(variant)).toEqual(PROVENANCE);
+      expect([variant.type, variant.width, variant.height]).toEqual([
+        'image/webp',
+        kind === 'stage' ? 1600 : 512,
+        kind === 'stage' ? 800 : 256,
+      ]);
+      expect(variant.size).toEqual(driver.store.get(variant.id)!.length);
+      // The hash is of THESE bytes, which the maker did not answer: never the original's.
+      expect(variant.contentHash ?? null).toBeNull();
+    }
+  });
+
+  it("the read path's door: the variant getVariant derives on the first request carries the original's provenance", async () => {
+    const file = await createOwnerPicture('existing.jpg', PROVENANCE);
+    expect((await rowAsSystem(file.id)).stage?._id ?? null).toBeNull();
+
+    const stage = (await new FileStorage().getVariant(file.id, 'stage'))!;
+
+    expect(stage.variantOf?._id).toEqual(file.id);
+    expect(provenanceOf(await rowAsSystem(stage.id))).toEqual(PROVENANCE);
+  });
+
+  it("the copy for others carries the original's provenance", async () => {
+    const file = await createOwnerPicture('shared.jpg', PROVENANCE);
+
+    const copy = await copyForOthersOf(file);
+
+    expect(copy.scope).toEqual(owner.id);
+    expect(provenanceOf(copy)).toEqual(PROVENANCE);
+    expect(copy.contentHash ?? null).toBeNull();
+  });
+
+  it('a row derived from a derived row carries what that row carries — its original’s: the copy for others of a stage variant', async () => {
+    const file = await createOwnerPicture('chain.jpg', PROVENANCE);
+    const stage = (await new FileStorage().getVariant(file.id, 'stage'))!;
+    reachableFileIds.add(file.id); // a variant's reachability is its original's: the grant names the original
+
+    const copyOfStage = await copyForOthersOf(await rowAsSystem(stage.id));
+
+    expect(copyOfStage.variantOf?._id ?? null).toBeNull(); // a copy's own id stays nobody's but the owner's
+    expect(provenanceOf(copyOfStage)).toEqual(PROVENANCE);
+  });
+
+  it('a row with NO provenance derives rows with none — nothing is invented, at any door', async () => {
+    const file = await createOwnerPicture('plain.jpg');
+    expect(provenanceOf(await rowAsSystem(file.id))).toEqual(NO_PROVENANCE);
+
+    const { variants } = await new FileStorage().deriveVariants(file, Buffer.concat([originalBytes, COPY_MARK]));
+    const copy = await copyForOthersOf(file);
+
+    expect(provenanceOf(await rowAsSystem(variants.preview!.id))).toEqual(NO_PROVENANCE);
+    expect(provenanceOf(await rowAsSystem(variants.stage!.id))).toEqual(NO_PROVENANCE);
+    expect(provenanceOf(copy)).toEqual(NO_PROVENANCE);
+  });
+});

package/test/FileMediaMetadata.test.ts

@@ -60,6 +60,49 @@ describe('File media metadata columns', () => {
     expect(row.durationMs).toEqual(24_500);
   });
 
+  it('round-trips the producer attribution — how the bytes came to exist (`origin`)', async () => {
+    const file = await new FileStorage().createFile(
+      { name: 'frame.png', type: 'image/png', size: 4, width: 1440, height: 900, origin: 'mockup' } as File,
+      Buffer.from('png!').toString('base64')
+    );
+
+    const row = await getDbAsSystem().get(tables.File, { id: file.id });
+    expect(row.origin).toEqual('mockup');
+    // Absent for everything that does not state its producer (a NULL column reads back empty).
+    const plain = await new FileStorage().createFile(
+      { name: 'note.txt', type: 'text/plain', size: 2 } as File,
+      Buffer.from('hi').toString('base64')
+    );
+    expect((await getDbAsSystem().get(tables.File, { id: plain.id })).origin).toBeFalsy();
+  });
+
+  it('round-trips the model beside the producer — which model made the bytes (`originModel`), only where one did', async () => {
+    const made = await new FileStorage().createFile(
+      {
+        name: 'mark.png',
+        type: 'image/png',
+        size: 4,
+        width: 1024,
+        height: 1024,
+        origin: 'generation',
+        originModel: 'example-image-model-1',
+      } as File,
+      Buffer.from('mark').toString('base64')
+    );
+    const madeRow = await getDbAsSystem().get(tables.File, { id: made.id });
+    expect(madeRow.origin).toEqual('generation');
+    expect(madeRow.originModel).toEqual('example-image-model-1');
+
+    // A producer that is not a model states its kind and no model: the two columns are independent.
+    const uploaded = await new FileStorage().createFile(
+      { name: 'photo.jpg', type: 'image/jpeg', size: 5, origin: 'upload' } as File,
+      Buffer.from('photo').toString('base64')
+    );
+    const uploadedRow = await getDbAsSystem().get(tables.File, { id: uploaded.id });
+    expect(uploadedRow.origin).toEqual('upload');
+    expect(uploadedRow.originModel).toBeFalsy();
+  });
+
   it('round-trips the rights record on a web-saved copy — licence name, deed URL and the credit sentence', async () => {
     const file = await new FileStorage().createFile(
       {
@@ -97,5 +140,6 @@ describe('File media metadata columns', () => {
     expect(row.durationMs ?? undefined).toBeUndefined();
     expect(row.license ?? undefined).toBeUndefined();
     expect(row.attribution ?? undefined).toBeUndefined();
+    expect(row.originModel ?? undefined).toBeUndefined();
   });
 });

package/test/FileStorageError.test.ts

@@ -0,0 +1,79 @@
+import util from 'util';
+import { FileStorageError } from '../src/FileStorageError';
+
+/** An obviously fake credential — what a store client's error carries in its request headers. */
+const MARKER = 'FAKE-TOKEN-MARKER';
+
+/**
+ * What a driver's error carries is the driver's to own: a code, a plain message, the HTTP status.
+ * Whatever a caller does with one — print it, serialise it, inspect it — reads those three facts.
+ */
+describe('FileStorageError', () => {
+  it('carries the code, a plain message and the status — and nothing else', () => {
+    const error = new FileStorageError('not-found', 'getFileData failed for file file-1', {
+      status: 404,
+      detail: 'No such object: a-bucket/file-1',
+    });
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.code).toEqual('not-found');
+    expect(error.status).toEqual(404);
+    expect(error.message).toEqual(
+      'getFileData failed for file file-1: not-found (HTTP 404) — No such object: a-bucket/file-1'
+    );
+    expect(Object.keys(error).sort()).toEqual(['code', 'name', 'status']);
+    expect(Object.getOwnPropertyNames(error).sort()).toEqual(['code', 'message', 'name', 'stack', 'status']);
+  });
+
+  it('never reads an object into its message — only text is kept as the store’s detail', () => {
+    const vendorError = { message: 'boom', config: { headers: { Authorization: `Bearer ${MARKER}` } } };
+
+    const error = new FileStorageError('unknown', 'createFile failed for file file-2', { detail: vendorError });
+
+    expect(error.message).toEqual('createFile failed for file file-2: unknown');
+    expect(util.inspect(error, { depth: null, showHidden: true })).not.toContain(MARKER);
+  });
+
+  it('keeps a store’s text plain: one line, bounded, no URL query string, no bearer credential', () => {
+    const detail =
+      `Request to https://storage.example/b/a-bucket/o/file-3?X-Goog-Signature=${MARKER}&X-Goog-Expires=900 failed\n` +
+      `with headers Authorization: Bearer ${MARKER} ` +
+      'x'.repeat(1000);
+
+    const error = new FileStorageError('unavailable', 'getSignedUrl failed for file file-3', { status: 503, detail });
+
+    expect(error.message).not.toContain(MARKER);
+    expect(error.message).not.toContain('\n');
+    expect(error.message).toContain('https://storage.example/b/a-bucket/o/file-3 failed');
+    expect(error.message).toContain('Bearer [masked]');
+    expect(error.message.length).toBeLessThan(400);
+  });
+
+  it('is recognised by its shape, so a copy from a duplicate package still reads as not-found', () => {
+    const fromAnotherCopy = Object.assign(new Error('getFileData failed'), {
+      name: 'FileStorageError',
+      code: 'not-found',
+    });
+
+    expect(FileStorageError.is(fromAnotherCopy)).toBe(true);
+    expect(FileStorageError.isNotFound(fromAnotherCopy)).toBe(true);
+    expect(FileStorageError.isNotFound(new FileStorageError('forbidden', 'getFileData failed'))).toBe(false);
+    expect(FileStorageError.is(Object.assign(new Error('a vendor error'), { code: 404 }))).toBe(false);
+    expect(FileStorageError.is(Object.assign(new Error('x'), { name: 'FileStorageError', code: 'made-up' }))).toBe(
+      false
+    );
+    expect(FileStorageError.is(undefined)).toBe(false);
+  });
+
+  it('reads one HTTP status one way', () => {
+    expect(FileStorageError.codeForStatus(404)).toEqual('not-found');
+    expect(FileStorageError.codeForStatus(412)).toEqual('precondition-failed');
+    expect(FileStorageError.codeForStatus(401)).toEqual('forbidden');
+    expect(FileStorageError.codeForStatus(403)).toEqual('forbidden');
+    expect(FileStorageError.codeForStatus(408)).toEqual('unavailable');
+    expect(FileStorageError.codeForStatus(429)).toEqual('unavailable');
+    expect(FileStorageError.codeForStatus(503)).toEqual('unavailable');
+    expect(FileStorageError.codeForStatus(400)).toEqual('unknown');
+    expect(FileStorageError.codeForStatus(undefined)).toEqual('unknown');
+  });
+});

package/test/FileTestEnvironment.ts

@@ -62,6 +62,9 @@ export class FileTestEnvironment {
     // implementations from the generated source graph; a graph-less harness lookup THROWS).
     // Default: no registered resolvers. Suites exercising the seam overwrite this entry.
     objectCache['@proteinjs/db-file/FileReachabilityResolver'] = [];
+    // The copy-for-others seam a non-owner read consults (same graph-less rule). Default: no
+    // maker — everyone is served the original. Suites exercising the seam overwrite this entry.
+    objectCache['@proteinjs/db-file/FileCopyForOthers'] = [];
     Session.setData({
       sessionId: 'test-session',
       user: 'guest',