graphile-presigned-url-plugin 0.5.0 → 0.6.1

package/esm/index.d.ts

@@ -29,6 +29,6 @@
 export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { PresignedUrlPreset } from './preset';
-export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
+export { getStorageModuleConfig, getStorageModuleConfigForOwner, getBucketConfig, resolveStorageModuleByFileId, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';
 export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, S3ConfigOrGetter, PresignedUrlPluginOptions, BucketNameResolver, EnsureBucketProvisioned, } from './types';

package/esm/index.js

@@ -29,5 +29,5 @@
 export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { PresignedUrlPreset } from './preset';
-export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
+export { getStorageModuleConfig, getStorageModuleConfigForOwner, getBucketConfig, resolveStorageModuleByFileId, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';

package/esm/plugin.js

@@ -19,7 +19,7 @@
 import { context as grafastContext, lambda, object } from 'grafast';
 import { extendSchema, gql } from 'graphile-utils';
 import { Logger } from '@pgpmjs/logger';
-import { getStorageModuleConfig, getBucketConfig, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
+import { getStorageModuleConfig, getStorageModuleConfigForOwner, getBucketConfig, resolveStorageModuleByFileId, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 import { generatePresignedPutUrl, headObject } from './s3-signer';
 const log = new Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
@@ -117,6 +117,13 @@ export function createPresignedUrlPlugin(options) {
       input RequestUploadUrlInput {
         """Bucket key (e.g., "public", "private")"""
         bucketKey: String!
+        """
+        Owner entity ID for entity-scoped uploads.
+        Omit for app-level (database-wide) storage.
+        When provided, resolves the storage module for the entity type
+        that owns this entity instance (e.g., a data room ID, team ID).
+        """
+        ownerId: UUID
         """SHA-256 content hash computed by the client (hex-encoded, 64 chars)"""
         contentHash: String!
         """MIME type of the file (e.g., "image/png")"""
@@ -188,7 +195,7 @@ export function createPresignedUrlPlugin(options) {
                     });
                     return lambda($combined, async ({ input, withPgClient, pgSettings }) => {
                         // --- Input validation ---
-                        const { bucketKey, contentHash, contentType, size, filename } = input;
+                        const { bucketKey, ownerId, contentHash, contentType, size, filename } = input;
                         if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
                             throw new Error('INVALID_BUCKET_KEY');
                         }
@@ -208,9 +215,14 @@ export function createPresignedUrlPlugin(options) {
                                 if (!databaseId) {
                                     throw new Error('DATABASE_NOT_FOUND');
                                 }
-                                const storageConfig = await getStorageModuleConfig(txClient, databaseId);
+                                // --- Resolve storage module (app-level or entity-scoped) ---
+                                const storageConfig = ownerId
+                                    ? await getStorageModuleConfigForOwner(txClient, databaseId, ownerId)
+                                    : await getStorageModuleConfig(txClient, databaseId);
                                 if (!storageConfig) {
-                                    throw new Error('STORAGE_MODULE_NOT_PROVISIONED');
+                                    throw new Error(ownerId
+                                        ? 'STORAGE_MODULE_NOT_FOUND_FOR_OWNER: no storage module found for the given ownerId'
+                                        : 'STORAGE_MODULE_NOT_PROVISIONED');
                                 }
                                 // --- Validate size against storage module default (bucket override checked below) ---
                                 if (typeof size !== 'number' || size <= 0 || size > storageConfig.defaultMaxFileSize) {
@@ -222,7 +234,7 @@ export function createPresignedUrlPlugin(options) {
                                     }
                                 }
                                 // --- Look up the bucket (cached; first miss queries via RLS) ---
-                                const bucket = await getBucketConfig(txClient, storageConfig, databaseId, bucketKey);
+                                const bucket = await getBucketConfig(txClient, storageConfig, databaseId, bucketKey, ownerId);
                                 if (!bucket) {
                                     throw new Error('BUCKET_NOT_FOUND');
                                 }
@@ -247,15 +259,15 @@ export function createPresignedUrlPlugin(options) {
                                     throw new Error(`FILE_TOO_LARGE: exceeds bucket max of ${bucket.max_file_size} bytes`);
                                 }
                                 const s3Key = buildS3Key(contentHash);
-                                // --- Dedup check: look for existing file with same content_hash in this bucket ---
+                                // --- Dedup check: look for existing file with same key (content hash) in this bucket ---
                                 const dedupResult = await txClient.query({
                                     text: `SELECT id, status
                    FROM ${storageConfig.filesQualifiedName}
-                   WHERE content_hash = $1
+                   WHERE key = $1
                      AND bucket_id = $2
                      AND status IN ('ready', 'processed')
                    LIMIT 1`,
-                                    values: [contentHash, bucket.id],
+                                    values: [s3Key, bucket.id],
                                 });
                                 if (dedupResult.rows.length > 0) {
                                     const existingFile = dedupResult.rows[0];
@@ -276,21 +288,36 @@ export function createPresignedUrlPlugin(options) {
                                     };
                                 }
                                 // --- Create file record (status=pending) ---
+                                // For app-level storage (no owner_id column), omit owner_id from the INSERT.
+                                const hasOwnerColumn = storageConfig.membershipType !== null;
                                 const fileResult = await txClient.query({
-                                    text: `INSERT INTO ${storageConfig.filesQualifiedName}
-                   (bucket_id, key, content_type, content_hash, size, filename, owner_id, is_public, status)
-                   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'pending')
-                   RETURNING id`,
-                                    values: [
-                                        bucket.id,
-                                        s3Key,
-                                        contentType,
-                                        contentHash,
-                                        size,
-                                        filename || null,
-                                        bucket.owner_id,
-                                        bucket.is_public,
-                                    ],
+                                    text: hasOwnerColumn
+                                        ? `INSERT INTO ${storageConfig.filesQualifiedName}
+                       (bucket_id, key, mime_type, size, filename, owner_id, is_public, status)
+                       VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending')
+                       RETURNING id`
+                                        : `INSERT INTO ${storageConfig.filesQualifiedName}
+                       (bucket_id, key, mime_type, size, filename, is_public, status)
+                       VALUES ($1, $2, $3, $4, $5, $6, 'pending')
+                       RETURNING id`,
+                                    values: hasOwnerColumn
+                                        ? [
+                                            bucket.id,
+                                            s3Key,
+                                            contentType,
+                                            size,
+                                            filename || null,
+                                            bucket.owner_id,
+                                            bucket.is_public,
+                                        ]
+                                        : [
+                                            bucket.id,
+                                            s3Key,
+                                            contentType,
+                                            size,
+                                            filename || null,
+                                            bucket.is_public,
+                                        ],
                                 });
                                 const fileId = fileResult.rows[0].id;
                                 // --- Ensure the S3 bucket exists (lazy provisioning) ---
@@ -333,27 +360,16 @@ export function createPresignedUrlPlugin(options) {
                         }
                         return withPgClient(pgSettings, async (pgClient) => {
                             return pgClient.withTransaction(async (txClient) => {
-                                // --- Resolve storage module config ---
+                                // --- Resolve storage module by file ID (probes all file tables) ---
                                 const databaseId = await resolveDatabaseId(txClient);
                                 if (!databaseId) {
                                     throw new Error('DATABASE_NOT_FOUND');
                                 }
-                                const storageConfig = await getStorageModuleConfig(txClient, databaseId);
-                                if (!storageConfig) {
-                                    throw new Error('STORAGE_MODULE_NOT_PROVISIONED');
-                                }
-                                // --- Look up the file (RLS enforced) ---
-                                const fileResult = await txClient.query({
-                                    text: `SELECT id, key, content_type, status, bucket_id
-                   FROM ${storageConfig.filesQualifiedName}
-                   WHERE id = $1
-                   LIMIT 1`,
-                                    values: [fileId],
-                                });
-                                if (fileResult.rows.length === 0) {
+                                const resolved = await resolveStorageModuleByFileId(txClient, databaseId, fileId);
+                                if (!resolved) {
                                     throw new Error('FILE_NOT_FOUND');
                                 }
-                                const file = fileResult.rows[0];
+                                const { storageConfig, file } = resolved;
                                 if (file.status !== 'pending') {
                                     // File is already confirmed or processed — idempotent success
                                     return {
@@ -364,12 +380,12 @@ export function createPresignedUrlPlugin(options) {
                                 }
                                 // --- Verify file exists in S3 (per-database bucket) ---
                                 const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
-                                const s3Head = await headObject(s3ForDb, file.key, file.content_type);
+                                const s3Head = await headObject(s3ForDb, file.key, file.mime_type);
                                 if (!s3Head) {
                                     throw new Error('FILE_NOT_IN_S3: the file has not been uploaded yet');
                                 }
                                 // --- Content-type verification ---
-                                if (s3Head.contentType && s3Head.contentType !== file.content_type) {
+                                if (s3Head.contentType && s3Head.contentType !== file.mime_type) {
                                     // Mark upload_request as rejected
                                     await txClient.query({
                                         text: `UPDATE ${storageConfig.uploadRequestsQualifiedName}
@@ -377,7 +393,7 @@ export function createPresignedUrlPlugin(options) {
                      WHERE file_id = $1 AND status = 'issued'`,
                                         values: [fileId],
                                     });
-                                    throw new Error(`CONTENT_TYPE_MISMATCH: expected ${file.content_type}, got ${s3Head.contentType}`);
+                                    throw new Error(`CONTENT_TYPE_MISMATCH: expected ${file.mime_type}, got ${s3Head.contentType}`);
                                 }
                                 // --- Transition file to 'ready' ---
                                 await txClient.query({

package/esm/storage-module-cache.d.ts

@@ -1,6 +1,9 @@
 import type { StorageModuleConfig, BucketConfig } from './types';
 /**
- * Resolve the storage module config for a database, using the LRU cache.
+ * Resolve the app-level storage module config for a database, using the LRU cache.
+ *
+ * This is the default path when no ownerId is provided. It returns the
+ * storage module with membership_type IS NULL (app-level / database-wide).
  *
  * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
  * @param databaseId - The metaschema database UUID
@@ -14,6 +17,57 @@ export declare function getStorageModuleConfig(pgClient: {
         rows: unknown[];
     }>;
 }, databaseId: string): Promise<StorageModuleConfig | null>;
+/**
+ * Resolve the storage module config for a specific owner entity.
+ *
+ * When ownerId is provided, this function:
+ * 1. Loads ALL storage modules for the database (cached)
+ * 2. Finds which entity-scoped module contains the ownerId in its entity table
+ * 3. Returns that module's config
+ *
+ * This is the core of Option C — the ownerId tells us which scope to use.
+ *
+ * @param pgClient - A pg client from the Graphile context
+ * @param databaseId - The metaschema database UUID
+ * @param ownerId - The entity instance UUID (e.g., a data room ID, team ID)
+ * @returns StorageModuleConfig or null if no matching module found
+ */
+export declare function getStorageModuleConfigForOwner(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, ownerId: string): Promise<StorageModuleConfig | null>;
+/**
+ * Resolve the storage module that owns a specific file by probing all file tables.
+ *
+ * Used by confirmUpload when only a fileId (UUID) is available.
+ * Since UUIDs are globally unique, exactly one table will contain the file.
+ *
+ * @param pgClient - A pg client from the Graphile context
+ * @param databaseId - The metaschema database UUID
+ * @param fileId - The file UUID to look up
+ * @returns Object with the storage config and file row, or null if not found
+ */
+export declare function resolveStorageModuleByFileId(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, fileId: string): Promise<{
+    storageConfig: StorageModuleConfig;
+    file: {
+        id: string;
+        key: string;
+        mime_type: string;
+        status: string;
+        bucket_id: string;
+    };
+} | null>;
 /**
  * Resolve bucket metadata for a given database + bucket key, using the LRU cache.
  *
@@ -21,9 +75,10 @@ export declare function getStorageModuleConfig(pgClient: {
  * the pgClient). On cache hit, returns the cached metadata directly.
  *
  * @param pgClient - A pg client from the Graphile context
- * @param storageConfig - The resolved StorageModuleConfig for this database
+ * @param storageConfig - The resolved StorageModuleConfig for this database/scope
  * @param databaseId - The metaschema database UUID (used as cache key prefix)
  * @param bucketKey - The bucket key (e.g., "public", "private")
+ * @param ownerId - Optional owner entity ID for entity-scoped bucket lookup
  * @returns BucketConfig or null if the bucket doesn't exist / isn't accessible
  */
 export declare function getBucketConfig(pgClient: {
@@ -33,7 +88,7 @@ export declare function getBucketConfig(pgClient: {
     }) => Promise<{
         rows: unknown[];
     }>;
-}, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: string): Promise<BucketConfig | null>;
+}, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: string, ownerId?: string): Promise<BucketConfig | null>;
 /**
  * Check whether an S3 bucket has already been provisioned (cached).
  */

package/esm/storage-module-cache.js

@@ -1,5 +1,6 @@
 import { Logger } from '@pgpmjs/logger';
 import { LRUCache } from 'lru-cache';
+import { QuoteUtils } from '@pgsql/quotes';
 const log = new Logger('graphile-presigned-url:cache');
 // --- Defaults ---
 const DEFAULT_UPLOAD_URL_EXPIRY_SECONDS = 900; // 15 minutes
@@ -25,13 +26,18 @@ const storageModuleCache = new LRUCache({
     updateAgeOnGet: true,
 });
 /**
- * SQL query to resolve storage module config for a database.
+ * SQL query to resolve the app-level storage module config for a database.
  *
  * Joins storage_module → table → schema to get fully-qualified table names.
+ * Filters to app-level (membership_type IS NULL) by default.
+ *
+ * Requires the multi-scope schema (membership_type column on storage_module).
  */
-const STORAGE_MODULE_QUERY = `
+const APP_STORAGE_MODULE_QUERY = `
   SELECT
     sm.id,
+    sm.membership_type,
+    sm.entity_table_id,
     bs.schema_name AS buckets_schema,
     bt.name AS buckets_table,
     fs.schema_name AS files_schema,
@@ -46,7 +52,9 @@ const STORAGE_MODULE_QUERY = `
     sm.download_url_expiry_seconds,
     sm.default_max_file_size,
     sm.max_filename_length,
-    sm.cache_ttl_seconds
+    sm.cache_ttl_seconds,
+    NULL AS entity_schema,
+    NULL AS entity_table
   FROM metaschema_modules_public.storage_module sm
   JOIN metaschema_public.table bt ON bt.id = sm.buckets_table_id
   JOIN metaschema_public.schema bs ON bs.id = bt.schema_id
@@ -55,38 +63,67 @@ const STORAGE_MODULE_QUERY = `
   JOIN metaschema_public.table urt ON urt.id = sm.upload_requests_table_id
   JOIN metaschema_public.schema urs ON urs.id = urt.schema_id
   WHERE sm.database_id = $1
+    AND sm.membership_type IS NULL
   LIMIT 1
 `;
 /**
- * Resolve the storage module config for a database, using the LRU cache.
+ * SQL query to resolve ALL storage modules for a database (app-level + entity-scoped).
  *
- * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
- * @param databaseId - The metaschema database UUID
- * @returns StorageModuleConfig or null if no storage module is provisioned
+ * Returns all storage modules with their entity table names for ownerId resolution.
+ * Requires the multi-scope schema.
  */
-export async function getStorageModuleConfig(pgClient, databaseId) {
-    const cacheKey = `storage:${databaseId}`;
-    const cached = storageModuleCache.get(cacheKey);
-    if (cached) {
-        return cached;
-    }
-    log.debug(`Cache miss for database ${databaseId}, querying metaschema...`);
-    const result = await pgClient.query({ text: STORAGE_MODULE_QUERY, values: [databaseId] });
-    if (result.rows.length === 0) {
-        log.warn(`No storage module found for database ${databaseId}`);
-        return null;
-    }
-    const row = result.rows[0];
+const ALL_STORAGE_MODULES_QUERY = `
+  SELECT
+    sm.id,
+    sm.membership_type,
+    sm.entity_table_id,
+    bs.schema_name AS buckets_schema,
+    bt.name AS buckets_table,
+    fs.schema_name AS files_schema,
+    ft.name AS files_table,
+    urs.schema_name AS upload_requests_schema,
+    urt.name AS upload_requests_table,
+    sm.endpoint,
+    sm.public_url_prefix,
+    sm.provider,
+    sm.allowed_origins,
+    sm.upload_url_expiry_seconds,
+    sm.download_url_expiry_seconds,
+    sm.default_max_file_size,
+    sm.max_filename_length,
+    sm.cache_ttl_seconds,
+    es.schema_name AS entity_schema,
+    et.name AS entity_table
+  FROM metaschema_modules_public.storage_module sm
+  JOIN metaschema_public.table bt ON bt.id = sm.buckets_table_id
+  JOIN metaschema_public.schema bs ON bs.id = bt.schema_id
+  JOIN metaschema_public.table ft ON ft.id = sm.files_table_id
+  JOIN metaschema_public.schema fs ON fs.id = ft.schema_id
+  JOIN metaschema_public.table urt ON urt.id = sm.upload_requests_table_id
+  JOIN metaschema_public.schema urs ON urs.id = urt.schema_id
+  LEFT JOIN metaschema_public.table et ON et.id = sm.entity_table_id
+  LEFT JOIN metaschema_public.schema es ON es.id = et.schema_id
+  WHERE sm.database_id = $1
+`;
+/**
+ * Build a StorageModuleConfig from a raw DB row.
+ */
+function buildConfig(row) {
     const cacheTtlSeconds = row.cache_ttl_seconds ?? DEFAULT_CACHE_TTL_SECONDS;
-    const config = {
+    return {
         id: row.id,
-        bucketsQualifiedName: `"${row.buckets_schema}"."${row.buckets_table}"`,
-        filesQualifiedName: `"${row.files_schema}"."${row.files_table}"`,
-        uploadRequestsQualifiedName: `"${row.upload_requests_schema}"."${row.upload_requests_table}"`,
+        bucketsQualifiedName: QuoteUtils.quoteQualifiedIdentifier(row.buckets_schema, row.buckets_table),
+        filesQualifiedName: QuoteUtils.quoteQualifiedIdentifier(row.files_schema, row.files_table),
+        uploadRequestsQualifiedName: QuoteUtils.quoteQualifiedIdentifier(row.upload_requests_schema, row.upload_requests_table),
         schemaName: row.buckets_schema,
         bucketsTableName: row.buckets_table,
         filesTableName: row.files_table,
         uploadRequestsTableName: row.upload_requests_table,
+        membershipType: row.membership_type,
+        entityTableId: row.entity_table_id,
+        entityQualifiedName: row.entity_schema && row.entity_table
+            ? QuoteUtils.quoteQualifiedIdentifier(row.entity_schema, row.entity_table)
+            : null,
         endpoint: row.endpoint,
         publicUrlPrefix: row.public_url_prefix,
         provider: row.provider,
@@ -97,10 +134,129 @@ export async function getStorageModuleConfig(pgClient, databaseId) {
         maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
         cacheTtlSeconds,
     };
+}
+/**
+ * Resolve the app-level storage module config for a database, using the LRU cache.
+ *
+ * This is the default path when no ownerId is provided. It returns the
+ * storage module with membership_type IS NULL (app-level / database-wide).
+ *
+ * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
+ * @param databaseId - The metaschema database UUID
+ * @returns StorageModuleConfig or null if no storage module is provisioned
+ */
+export async function getStorageModuleConfig(pgClient, databaseId) {
+    const cacheKey = `storage:${databaseId}:app`;
+    const cached = storageModuleCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    log.debug(`Cache miss for app-level storage in database ${databaseId}, querying metaschema...`);
+    const result = await pgClient.query({ text: APP_STORAGE_MODULE_QUERY, values: [databaseId] });
+    if (result.rows.length === 0) {
+        log.warn(`No app-level storage module found for database ${databaseId}`);
+        return null;
+    }
+    const config = buildConfig(result.rows[0]);
     storageModuleCache.set(cacheKey, config);
-    log.debug(`Cached storage config for database ${databaseId}: ${config.bucketsQualifiedName}`);
+    log.debug(`Cached app-level storage config for database ${databaseId}: ${config.bucketsQualifiedName}`);
     return config;
 }
+/**
+ * Resolve the storage module config for a specific owner entity.
+ *
+ * When ownerId is provided, this function:
+ * 1. Loads ALL storage modules for the database (cached)
+ * 2. Finds which entity-scoped module contains the ownerId in its entity table
+ * 3. Returns that module's config
+ *
+ * This is the core of Option C — the ownerId tells us which scope to use.
+ *
+ * @param pgClient - A pg client from the Graphile context
+ * @param databaseId - The metaschema database UUID
+ * @param ownerId - The entity instance UUID (e.g., a data room ID, team ID)
+ * @returns StorageModuleConfig or null if no matching module found
+ */
+export async function getStorageModuleConfigForOwner(pgClient, databaseId, ownerId) {
+    // Check if we already have a cached mapping for this ownerId
+    const ownerCacheKey = `storage:${databaseId}:owner:${ownerId}`;
+    const cachedOwner = storageModuleCache.get(ownerCacheKey);
+    if (cachedOwner) {
+        return cachedOwner;
+    }
+    // Load all storage modules for this database
+    const allModulesCacheKey = `storage:${databaseId}:all`;
+    let allConfigs;
+    const cachedAll = storageModuleCache.get(allModulesCacheKey);
+    if (cachedAll) {
+        // We stored a sentinel; re-derive from individual caches
+        // Actually, let's just query fresh — this is the cache-miss path
+        allConfigs = [];
+    }
+    else {
+        allConfigs = [];
+    }
+    if (allConfigs.length === 0) {
+        log.debug(`Loading all storage modules for database ${databaseId} to resolve ownerId ${ownerId}`);
+        const result = await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] });
+        allConfigs = result.rows.map(buildConfig);
+        // Cache each individual config by its membership type
+        for (const config of allConfigs) {
+            const key = config.membershipType === null
+                ? `storage:${databaseId}:app`
+                : `storage:${databaseId}:mt:${config.membershipType}`;
+            storageModuleCache.set(key, config);
+        }
+    }
+    // Find entity-scoped modules and probe their entity tables for the ownerId
+    const entityModules = allConfigs.filter((c) => c.entityQualifiedName !== null);
+    for (const mod of entityModules) {
+        const probeResult = await pgClient.query({
+            text: `SELECT 1 FROM ${mod.entityQualifiedName} WHERE id = $1 LIMIT 1`,
+            values: [ownerId],
+        });
+        if (probeResult.rows.length > 0) {
+            // Found the matching module — cache the ownerId→module mapping
+            storageModuleCache.set(ownerCacheKey, mod);
+            log.debug(`Resolved ownerId ${ownerId} to storage module ${mod.id} ` +
+                `(membershipType=${mod.membershipType}, table=${mod.bucketsQualifiedName})`);
+            return mod;
+        }
+    }
+    log.warn(`No entity-scoped storage module found for ownerId ${ownerId} in database ${databaseId}`);
+    return null;
+}
+/**
+ * Resolve the storage module that owns a specific file by probing all file tables.
+ *
+ * Used by confirmUpload when only a fileId (UUID) is available.
+ * Since UUIDs are globally unique, exactly one table will contain the file.
+ *
+ * @param pgClient - A pg client from the Graphile context
+ * @param databaseId - The metaschema database UUID
+ * @param fileId - The file UUID to look up
+ * @returns Object with the storage config and file row, or null if not found
+ */
+export async function resolveStorageModuleByFileId(pgClient, databaseId, fileId) {
+    // Load all storage modules for this database
+    log.debug(`Resolving file ${fileId} across all storage modules for database ${databaseId}`);
+    const allConfigs = (await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] })).rows.map((row) => buildConfig(row));
+    // Probe each module's files table for the fileId
+    for (const config of allConfigs) {
+        const fileResult = await pgClient.query({
+            text: `SELECT id, key, mime_type, status, bucket_id
+       FROM ${config.filesQualifiedName}
+       WHERE id = $1
+       LIMIT 1`,
+            values: [fileId],
+        });
+        if (fileResult.rows.length > 0) {
+            const file = fileResult.rows[0];
+            return { storageConfig: config, file };
+        }
+    }
+    return null;
+}
 // --- Bucket metadata cache ---
 /**
  * LRU cache for per-database bucket metadata.
@@ -113,7 +269,7 @@ export async function getStorageModuleConfig(pgClient, databaseId) {
  * is safe. The important RLS is on the files table (INSERT/UPDATE),
  * which is never cached.
  *
- * Keys: `bucket:${databaseId}:${bucketKey}`
+ * Keys: `bucket:${databaseId}:${storageModuleId}:${bucketKey}`
  * TTL: same as storage module cache (5min dev / 1hr prod)
  */
 const bucketCache = new LRUCache({
@@ -128,24 +284,33 @@ const bucketCache = new LRUCache({
  * the pgClient). On cache hit, returns the cached metadata directly.
  *
  * @param pgClient - A pg client from the Graphile context
- * @param storageConfig - The resolved StorageModuleConfig for this database
+ * @param storageConfig - The resolved StorageModuleConfig for this database/scope
  * @param databaseId - The metaschema database UUID (used as cache key prefix)
  * @param bucketKey - The bucket key (e.g., "public", "private")
+ * @param ownerId - Optional owner entity ID for entity-scoped bucket lookup
  * @returns BucketConfig or null if the bucket doesn't exist / isn't accessible
  */
-export async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey) {
-    const cacheKey = `bucket:${databaseId}:${bucketKey}`;
+export async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, ownerId) {
+    const cacheKey = `bucket:${databaseId}:${storageConfig.id}:${bucketKey}${ownerId ? `:${ownerId}` : ''}`;
     const cached = bucketCache.get(cacheKey);
     if (cached) {
         return cached;
     }
-    log.debug(`Bucket cache miss for ${databaseId}:${bucketKey}, querying DB...`);
+    log.debug(`Bucket cache miss for ${databaseId}:${bucketKey}${ownerId ? ` (owner=${ownerId})` : ''}, querying DB...`);
+    // Entity-scoped buckets use (owner_id, key) composite lookup;
+    // app-level buckets just use key.
+    const hasOwner = ownerId && storageConfig.membershipType !== null;
     const result = await pgClient.query({
-        text: `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size
-     FROM ${storageConfig.bucketsQualifiedName}
-     WHERE key = $1
-     LIMIT 1`,
-        values: [bucketKey],
+        text: hasOwner
+            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size
+         FROM ${storageConfig.bucketsQualifiedName}
+         WHERE key = $1 AND owner_id = $2
+         LIMIT 1`
+            : `SELECT id, key, type, is_public, ${storageConfig.membershipType !== null ? 'owner_id,' : ''} allowed_mime_types, max_file_size
+         FROM ${storageConfig.bucketsQualifiedName}
+         WHERE key = $1
+         LIMIT 1`,
+        values: hasOwner ? [bucketKey, ownerId] : [bucketKey],
     });
     if (result.rows.length === 0) {
         return null;
@@ -156,12 +321,12 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
         key: row.key,
         type: row.type,
         is_public: row.is_public,
-        owner_id: row.owner_id,
+        owner_id: row.owner_id ?? null,
         allowed_mime_types: row.allowed_mime_types,
         max_file_size: row.max_file_size,
     };
     bucketCache.set(cacheKey, config);
-    log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id})`);
+    log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.membershipType ?? 'app'})`);
     return config;
 }
 // --- S3 bucket existence cache ---

package/esm/types.d.ts

@@ -7,7 +7,7 @@ export interface BucketConfig {
     key: string;
     type: 'public' | 'private' | 'temp';
     is_public: boolean;
-    owner_id: string;
+    owner_id: string | null;
     allowed_mime_types: string[] | null;
     max_file_size: number | null;
 }
@@ -31,6 +31,12 @@ export interface StorageModuleConfig {
     filesTableName: string;
     /** Upload requests table name */
     uploadRequestsTableName: string;
+    /** Membership type (NULL for app-level, non-NULL for entity-scoped) */
+    membershipType: number | null;
+    /** Entity table ID for entity-scoped storage (NULL for app-level) */
+    entityTableId: string | null;
+    /** Qualified entity table name for ownerId lookups (NULL for app-level) */
+    entityQualifiedName: string | null;
     /** S3-compatible API endpoint URL (per-database override) */
     endpoint: string | null;
     /** Public URL prefix for generating download URLs (per-database override) */
@@ -56,6 +62,13 @@ export interface StorageModuleConfig {
 export interface RequestUploadUrlInput {
     /** Bucket key (e.g., "public", "private") */
     bucketKey: string;
+    /**
+     * Owner entity ID for entity-scoped uploads.
+     * Omit for app-level (database-wide) storage.
+     * When provided, resolves the storage module for the entity type
+     * that owns this entity instance (e.g., a data room ID, team ID).
+     */
+    ownerId?: string;
     /** SHA-256 content hash computed by the client */
     contentHash: string;
     /** MIME type of the file */

package/index.d.ts

@@ -29,6 +29,6 @@
 export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { PresignedUrlPreset } from './preset';
-export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
+export { getStorageModuleConfig, getStorageModuleConfigForOwner, getBucketConfig, resolveStorageModuleByFileId, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';
 export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, S3ConfigOrGetter, PresignedUrlPluginOptions, BucketNameResolver, EnsureBucketProvisioned, } from './types';