graphile-presigned-url-plugin 0.5.0 → 0.6.0

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');
                                 }
@@ -276,21 +288,38 @@ 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, content_type, content_hash, size, filename, owner_id, is_public, status)
+                       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'pending')
+                       RETURNING id`
+                                        : `INSERT INTO ${storageConfig.filesQualifiedName}
+                       (bucket_id, key, content_type, content_hash, size, filename, is_public, status)
+                       VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending')
+                       RETURNING id`,
+                                    values: hasOwnerColumn
+                                        ? [
+                                            bucket.id,
+                                            s3Key,
+                                            contentType,
+                                            contentHash,
+                                            size,
+                                            filename || null,
+                                            bucket.owner_id,
+                                            bucket.is_public,
+                                        ]
+                                        : [
+                                            bucket.id,
+                                            s3Key,
+                                            contentType,
+                                            contentHash,
+                                            size,
+                                            filename || null,
+                                            bucket.is_public,
+                                        ],
                                 });
                                 const fileId = fileResult.rows[0].id;
                                 // --- Ensure the S3 bucket exists (lazy provisioning) ---
@@ -333,27 +362,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 {

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;
+        content_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, content_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';

package/index.js

@@ -28,7 +28,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.headObject = exports.generatePresignedGetUrl = exports.generatePresignedPutUrl = exports.markS3BucketProvisioned = exports.isS3BucketProvisioned = exports.clearBucketCache = exports.clearStorageModuleCache = exports.getBucketConfig = exports.getStorageModuleConfig = exports.PresignedUrlPreset = exports.createDownloadUrlPlugin = exports.createPresignedUrlPlugin = exports.PresignedUrlPlugin = void 0;
+exports.headObject = exports.generatePresignedGetUrl = exports.generatePresignedPutUrl = exports.markS3BucketProvisioned = exports.isS3BucketProvisioned = exports.clearBucketCache = exports.clearStorageModuleCache = exports.resolveStorageModuleByFileId = exports.getBucketConfig = exports.getStorageModuleConfigForOwner = exports.getStorageModuleConfig = exports.PresignedUrlPreset = exports.createDownloadUrlPlugin = exports.createPresignedUrlPlugin = exports.PresignedUrlPlugin = void 0;
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "PresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.PresignedUrlPlugin; } });
 Object.defineProperty(exports, "createPresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.createPresignedUrlPlugin; } });
@@ -38,7 +38,9 @@ var preset_1 = require("./preset");
 Object.defineProperty(exports, "PresignedUrlPreset", { enumerable: true, get: function () { return preset_1.PresignedUrlPreset; } });
 var storage_module_cache_1 = require("./storage-module-cache");
 Object.defineProperty(exports, "getStorageModuleConfig", { enumerable: true, get: function () { return storage_module_cache_1.getStorageModuleConfig; } });
+Object.defineProperty(exports, "getStorageModuleConfigForOwner", { enumerable: true, get: function () { return storage_module_cache_1.getStorageModuleConfigForOwner; } });
 Object.defineProperty(exports, "getBucketConfig", { enumerable: true, get: function () { return storage_module_cache_1.getBucketConfig; } });
+Object.defineProperty(exports, "resolveStorageModuleByFileId", { enumerable: true, get: function () { return storage_module_cache_1.resolveStorageModuleByFileId; } });
 Object.defineProperty(exports, "clearStorageModuleCache", { enumerable: true, get: function () { return storage_module_cache_1.clearStorageModuleCache; } });
 Object.defineProperty(exports, "clearBucketCache", { enumerable: true, get: function () { return storage_module_cache_1.clearBucketCache; } });
 Object.defineProperty(exports, "isS3BucketProvisioned", { enumerable: true, get: function () { return storage_module_cache_1.isS3BucketProvisioned; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl, confirmUpload mutations and downloadUrl computed field",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -43,6 +43,7 @@
     "@aws-sdk/client-s3": "^3.1009.0",
     "@aws-sdk/s3-request-presigner": "^3.1009.0",
     "@pgpmjs/logger": "^2.6.0",
+    "@pgsql/quotes": "^17.1.0",
     "lru-cache": "^11.2.7"
   },
   "peerDependencies": {
@@ -59,5 +60,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.1.10"
   },
-  "gitHead": "1b3af3c5189b9ca2e765b9239a4b287099e64a03"
+  "gitHead": "28734dd71a973b2fe296e8240c8f86c568b4292f"
 }

package/plugin.js

@@ -121,6 +121,13 @@ 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")"""
@@ -192,7 +199,7 @@ function createPresignedUrlPlugin(options) {
                     });
                     return (0, grafast_1.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');
                         }
@@ -212,9 +219,14 @@ function createPresignedUrlPlugin(options) {
                                 if (!databaseId) {
                                     throw new Error('DATABASE_NOT_FOUND');
                                 }
-                                const storageConfig = await (0, storage_module_cache_1.getStorageModuleConfig)(txClient, databaseId);
+                                // --- Resolve storage module (app-level or entity-scoped) ---
+                                const storageConfig = ownerId
+                                    ? await (0, storage_module_cache_1.getStorageModuleConfigForOwner)(txClient, databaseId, ownerId)
+                                    : await (0, storage_module_cache_1.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) {
@@ -226,7 +238,7 @@ function createPresignedUrlPlugin(options) {
                                     }
                                 }
                                 // --- Look up the bucket (cached; first miss queries via RLS) ---
-                                const bucket = await (0, storage_module_cache_1.getBucketConfig)(txClient, storageConfig, databaseId, bucketKey);
+                                const bucket = await (0, storage_module_cache_1.getBucketConfig)(txClient, storageConfig, databaseId, bucketKey, ownerId);
                                 if (!bucket) {
                                     throw new Error('BUCKET_NOT_FOUND');
                                 }
@@ -280,21 +292,38 @@ 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, content_type, content_hash, size, filename, owner_id, is_public, status)
+                       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'pending')
+                       RETURNING id`
+                                        : `INSERT INTO ${storageConfig.filesQualifiedName}
+                       (bucket_id, key, content_type, content_hash, size, filename, is_public, status)
+                       VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending')
+                       RETURNING id`,
+                                    values: hasOwnerColumn
+                                        ? [
+                                            bucket.id,
+                                            s3Key,
+                                            contentType,
+                                            contentHash,
+                                            size,
+                                            filename || null,
+                                            bucket.owner_id,
+                                            bucket.is_public,
+                                        ]
+                                        : [
+                                            bucket.id,
+                                            s3Key,
+                                            contentType,
+                                            contentHash,
+                                            size,
+                                            filename || null,
+                                            bucket.is_public,
+                                        ],
                                 });
                                 const fileId = fileResult.rows[0].id;
                                 // --- Ensure the S3 bucket exists (lazy provisioning) ---
@@ -337,27 +366,16 @@ 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 (0, storage_module_cache_1.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 (0, storage_module_cache_1.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 {

package/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;
+        content_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/storage-module-cache.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getStorageModuleConfig = getStorageModuleConfig;
+exports.getStorageModuleConfigForOwner = getStorageModuleConfigForOwner;
+exports.resolveStorageModuleByFileId = resolveStorageModuleByFileId;
 exports.getBucketConfig = getBucketConfig;
 exports.isS3BucketProvisioned = isS3BucketProvisioned;
 exports.markS3BucketProvisioned = markS3BucketProvisioned;
@@ -8,6 +10,7 @@ exports.clearStorageModuleCache = clearStorageModuleCache;
 exports.clearBucketCache = clearBucketCache;
 const logger_1 = require("@pgpmjs/logger");
 const lru_cache_1 = require("lru-cache");
+const quotes_1 = require("@pgsql/quotes");
 const log = new logger_1.Logger('graphile-presigned-url:cache');
 // --- Defaults ---
 const DEFAULT_UPLOAD_URL_EXPIRY_SECONDS = 900; // 15 minutes
@@ -33,13 +36,18 @@ const storageModuleCache = new lru_cache_1.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,
@@ -54,7 +62,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
@@ -63,38 +73,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.
  */
-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: quotes_1.QuoteUtils.quoteQualifiedIdentifier(row.buckets_schema, row.buckets_table),
+        filesQualifiedName: quotes_1.QuoteUtils.quoteQualifiedIdentifier(row.files_schema, row.files_table),
+        uploadRequestsQualifiedName: quotes_1.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
+            ? quotes_1.QuoteUtils.quoteQualifiedIdentifier(row.entity_schema, row.entity_table)
+            : null,
         endpoint: row.endpoint,
         publicUrlPrefix: row.public_url_prefix,
         provider: row.provider,
@@ -105,10 +144,129 @@ 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
+ */
+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
+ */
+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
+ */
+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, content_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.
@@ -121,7 +279,7 @@ 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 lru_cache_1.LRUCache({
@@ -136,24 +294,33 @@ const bucketCache = new lru_cache_1.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
  */
-async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey) {
-    const cacheKey = `bucket:${databaseId}:${bucketKey}`;
+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;
@@ -164,12 +331,12 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey) {
         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/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 */