@proteinjs/db-file 1.7.3 → 1.7.4

package/src/FileStorage.ts

@@ -1,8 +1,9 @@
-import { ScopedRecord, getScopedDb } from '@proteinjs/user';
+import { ScopedRecord, getScopedDb, getScopedDbAsSystem } from '@proteinjs/user';
 import { File } from './tables/FileTable';
 import { tables } from './tables/tables';
 import { FileStorageService, getFileStorageService } from './services/FileStorageService';
 import { FileStorageDriver } from './FileStorageDriver';
+import { getFileReachabilityResolvers } from './FileReachabilityResolver';
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { Logger } from '@proteinjs/logger';
 import { DbFileStorageDriver } from './DbFileStorageDriver';
@@ -73,13 +74,32 @@ export class FileStorage implements FileStorageService {
   }
 
   /**
-   * Retrieves the metadata of a given file.
+   * Retrieves the metadata of a given file — THE file-read access decision every serving path
+   * derives from (`/file/:id`, signed-URL minting, the browser service).
+   *
+   * Two legs: the caller's own file resolves by the SCOPED read; when that misses, the
+   * shared-content leg asks the registered {@link FileReachabilityResolver}s whether the caller
+   * can read a row that REFERENCES the file (a shared thought's media node) — content access
+   * confers file access, through the content's own grant-filtered read, never by widening file
+   * scope. No resolver vouching means the miss stands. Reads only: writes/deletes stay scoped.
    * @param fileId - The `id` of the file.
-   * @returns The file metadata.
+   * @returns The file metadata, or `undefined` when the caller can neither own nor reach it.
    */
   async getFile(fileId: string): Promise<File> {
     const db = getScopedDb();
     const file = await db.get(tables.File, { id: fileId });
+    if (file) {
+      return file;
+    }
+
+    for (const resolver of getFileReachabilityResolvers()) {
+      if (await resolver.canReadViaReference(fileId)) {
+        // Reachability established through the caller's grant-filtered content read — the row
+        // itself lives in the owner's scope, so it is served via system read.
+        return await getScopedDbAsSystem().get(tables.File, { id: fileId });
+      }
+    }
+
     return file;
   }
 
@@ -95,7 +115,8 @@ export class FileStorage implements FileStorageService {
   /**
    * Mint a short-lived, read-only URL for the file's bytes (server-only; not part of the
    * browser-facing `FileStorageService`). A signed URL is a bearer capability, so minting
-   * verifies the caller can read the file row (scoped read) before signing.
+   * verifies the caller can read the file row (the two-legged {@link getFile} read — own scope
+   * or shared-content reachability) before signing.
    * @param fileId - The `id` of the file.
    * @param options.ttlMs - How long the URL stays valid; the driver applies its default when omitted.
    * @returns The signed URL, or `undefined` when the driver has no external URL space

package/src/routes/getFile.ts

@@ -4,7 +4,10 @@ import { UserAuth } from '@proteinjs/user';
 import { resolveByteRange } from './byteRange';
 
 /**
- * Serves a file's bytes. Auth first (logged-in + scoped row read), then one of two paths:
+ * Serves a file's bytes. Auth first: logged-in, then the `FileStorage.getFile` row read as the
+ * access decision — the caller's SCOPED read, else the shared-content reachability leg
+ * (`FileReachabilityResolver`: the caller may read a file when they may read a row that
+ * references it, e.g. a shared thought's media node). Then one of two serving paths:
  *
  * - **302 redirect** to a short-lived signed URL when the driver's store has an external URL
  *   space (GCS). The app URL stays the one stable reference every `<img>`/`<video>`/chip uses;
@@ -28,7 +31,7 @@ export const getFile: Route = {
     const fileId = request.params.id;
     const fileStorage = getFileStorage();
     try {
-      // The file row decides existence (a scoped read, so it is also the access check).
+      // The file row decides existence (a scoped-or-reachable read, so it is also the access check).
       const file = await fileStorage.getFile(fileId);
       if (!file) {
         response.status(404).send('File not found');

package/test/FileSharedReachability.test.ts

@@ -0,0 +1,229 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import { UserAuth, UserRepo, User } from '@proteinjs/user';
+import { File } from '../src/tables/FileTable';
+import { FileStorage } from '../src/FileStorage';
+import { FileStorageDriver } from '../src/FileStorageDriver';
+import { getFile } from '../src/routes/getFile';
+import { FileTestEnvironment } from './FileTestEnvironment';
+
+/** Every byte value once — a payload that corrupts under any text/base64 mix-up. */
+const rawBytes = Buffer.from(Array.from({ length: 256 }, (_, i) => i));
+
+/**
+ * The shared-content file leg (SHARING_EXPANSION §0 found defect / §1 fix shape): `/file/:id`
+ * used the caller's SCOPED row read as its whole access check, so a file embedded in content
+ * shared WITH the caller — a shared thought's media — 404'd for every share recipient. The fix
+ * is the FileReachabilityResolver seam: after the scoped read misses, content packages answer
+ * "can the current user read a row that references this file?" through their own grant-filtered
+ * reads, and only then is the row served via system read.
+ *
+ * This suite proves the SEAM CONTRACT at the route with a stub resolver (content packages sit
+ * above db-file — the real thought-media resolver is integration-tested in thought-server):
+ * a reachable file serves byte-identical to a non-owner, an unreachable one still 404s (the fix
+ * must not over-open), the owner's scoped leg never consults resolvers, and writes stay
+ * owner-scoped.
+ */
+
+/** 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);
+  }
+}
+
+/** Proxy driver plus a counting signed-URL mint — the GCS serving shape, minting observable. */
+class SignedUrlDriver extends ProxyDriver {
+  mintCount = 0;
+
+  async getSignedUrl(fileId: string): Promise<string> {
+    this.mintCount++;
+    return `https://signed.test/blob/${fileId}?sig=test`;
+  }
+}
+
+/** Minimal express Response recorder — the route only touches these members. */
+class ResponseRecorder {
+  statusCode?: number;
+  body?: unknown;
+  redirectUrl?: string;
+  headers: Record<string, string> = {};
+
+  status(code: number): ResponseRecorder {
+    this.statusCode = code;
+    return this;
+  }
+
+  send(body: unknown): ResponseRecorder {
+    this.body = body;
+    return this;
+  }
+
+  setHeader(name: string, value: string): void {
+    this.headers[name.toLowerCase()] = value;
+  }
+
+  redirect(status: number, url: string): void {
+    this.statusCode = status;
+    this.redirectUrl = url;
+  }
+}
+
+type RouteRequest = Parameters<typeof getFile.onRequest>[0];
+type RouteResponse = Parameters<typeof getFile.onRequest>[1];
+
+const invokeRoute = async (fileId: string): Promise<ResponseRecorder> => {
+  const response = new ResponseRecorder();
+  await getFile.onRequest(
+    { params: { id: fileId }, headers: {} } as unknown as RouteRequest,
+    response as unknown as RouteResponse
+  );
+  return response;
+};
+
+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;
+/** File ids the stub resolver reports as reachable for the current user. */
+const reachableFileIds = new Set<string>();
+/** How many times the seam was consulted — the owner's scoped leg must never pay for it. */
+let resolverConsultations = 0;
+
+beforeAll(async () => {
+  await testEnv.beforeAll();
+  // The route gates on UserAuth.isLoggedIn(), which resolves its user repo from the source
+  // repository — seed it (tests don't load the generated source graph) and reset the static cache.
+  objectCache()['@proteinjs/user-auth/AuthenticatedUserRepo'] = [new UserRepo()];
+  (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+  // The seam under test, stubbed (the real thought-media resolver lives above this package).
+  objectCache()['@proteinjs/db-file/FileReachabilityResolver'] = [
+    {
+      canReadViaReference: async (fileId: string) => {
+        resolverConsultations++;
+        return reachableFileIds.has(fileId);
+      },
+    },
+  ];
+  owner = await testEnv.createUser({ name: 'File owner', email: 'reachability-owner@test.local' });
+  recipient = await testEnv.createUser({ name: 'Share recipient', email: 'reachability-recipient@test.local' });
+  testEnv.actAs(owner);
+});
+
+afterAll(async () => {
+  delete objectCache()['@proteinjs/db-file/FileReachabilityResolver'];
+  (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+  await testEnv.afterAll();
+});
+
+beforeEach(() => {
+  reachableFileIds.clear();
+  resolverConsultations = 0;
+  testEnv.actAs(owner);
+});
+
+const createOwnerFile = async (name: string, type: string): Promise<File> =>
+  await new FileStorage().createFile({ name, type, size: rawBytes.length } as File, rawBytes.toString('base64'));
+
+describe('shared-content reachability — proxy serving', () => {
+  const driver = new ProxyDriver();
+
+  beforeAll(() => {
+    testEnv.setDriver(driver);
+  });
+
+  it("THE DEFECT: a non-owner whom a resolver vouches for is served the owner's file byte-identical", async () => {
+    const file = await createOwnerFile('shared-shot.png', 'image/png');
+    reachableFileIds.add(file.id);
+
+    testEnv.actAs(recipient);
+    const response = await invokeRoute(file.id);
+
+    expect(response.statusCode).not.toEqual(404);
+    expect(response.headers['content-type']).toEqual('image/png');
+    expect(Buffer.isBuffer(response.body)).toBe(true);
+    expect(Buffer.compare(response.body as Buffer, rawBytes)).toBe(0);
+  });
+
+  it('THE OTHER DIRECTION: a non-owner with no reachability still 404s — the fix must not over-open', async () => {
+    const file = await createOwnerFile('private-shot.png', 'image/png');
+
+    testEnv.actAs(recipient);
+    const response = await invokeRoute(file.id);
+
+    expect(response.statusCode).toEqual(404);
+    expect(response.body).toEqual('File not found');
+  });
+
+  it('the owner is served by their scoped read alone — resolvers are never consulted', async () => {
+    const file = await createOwnerFile('own-shot.png', 'image/png');
+
+    const response = await invokeRoute(file.id);
+
+    expect(Buffer.compare(response.body as Buffer, rawBytes)).toBe(0);
+    expect(resolverConsultations).toEqual(0);
+  });
+
+  it("reachability widens READS only: a vouched-for non-owner's delete leaves the owner's file intact", async () => {
+    const file = await createOwnerFile('undeletable.png', 'image/png');
+    reachableFileIds.add(file.id);
+
+    testEnv.actAs(recipient);
+    await new FileStorage().deleteFile(file.id);
+
+    testEnv.actAs(owner);
+    const response = await invokeRoute(file.id);
+    expect(Buffer.compare(response.body as Buffer, rawBytes)).toBe(0);
+  });
+});
+
+describe('shared-content reachability — signed-URL serving', () => {
+  const driver = new SignedUrlDriver();
+
+  beforeAll(() => {
+    testEnv.setDriver(driver);
+  });
+
+  it('302-redirects a vouched-for non-owner to a signed URL (the GCS prod shape)', async () => {
+    const file = await createOwnerFile('shared-clip.mp4', 'video/mp4');
+    reachableFileIds.add(file.id);
+
+    testEnv.actAs(recipient);
+    const response = await invokeRoute(file.id);
+
+    expect(response.statusCode).toEqual(302);
+    expect(response.redirectUrl).toEqual(`https://signed.test/blob/${file.id}?sig=test`);
+  });
+
+  it('404s an unreachable non-owner WITHOUT minting a signed URL (a signed URL is a bearer capability)', async () => {
+    const file = await createOwnerFile('private-clip.mp4', 'video/mp4');
+    const mintsBefore = driver.mintCount;
+
+    testEnv.actAs(recipient);
+    const response = await invokeRoute(file.id);
+
+    expect(response.statusCode).toEqual(404);
+    expect(response.redirectUrl).toBeUndefined();
+    expect(driver.mintCount).toEqual(mintsBefore);
+  });
+});

package/test/FileTestEnvironment.ts

@@ -58,6 +58,10 @@ export class FileTestEnvironment {
     objectCache['@proteinjs/db/Table'] = [...Object.values(userTables), ...Object.values(fileTables)] as unknown[];
     // The byte-deletion seam under test: prod loads it from the generated source graph.
     objectCache['@proteinjs/db/TableWatcher'] = [new FileStorageTableWatcher()];
+    // The shared-content reachability seam getFile consults on a scoped-read miss (prod loads
+    // 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'] = [];
     Session.setData({
       sessionId: 'test-session',
       user: 'guest',