graphile-presigned-url-plugin 0.8.0 → 0.10.0

package/esm/plugin.js

@@ -22,7 +22,9 @@ const log = new Logger('graphile-presigned-url:plugin');
 const MAX_CONTENT_HASH_LENGTH = 128;
 const MAX_CONTENT_TYPE_LENGTH = 255;
 const MAX_BUCKET_KEY_LENGTH = 255;
+const MAX_CUSTOM_KEY_LENGTH = 1024;
 const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/;
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_.\-\/]*$/;
 // --- Helpers ---
 /**
  * Validate a SHA-256 hex string.
@@ -31,12 +33,46 @@ function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
 }
 /**
- * Build the S3 key from content hash and content type extension.
+ * Build the S3 key from content hash.
  * Format: {contentHash} (flat namespace, content-addressed)
  */
 function buildS3Key(contentHash) {
     return contentHash;
 }
+/**
+ * Validate a custom S3 key.
+ * Must be 1-1024 chars, no path traversal, no leading slash, no null bytes.
+ */
+function validateCustomKey(key) {
+    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
+        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
+    }
+    if (key.includes('..')) {
+        return 'INVALID_KEY: path traversal (..) not allowed';
+    }
+    if (key.startsWith('/')) {
+        return 'INVALID_KEY: leading slash not allowed';
+    }
+    if (key.includes('\0')) {
+        return 'INVALID_KEY: null bytes not allowed';
+    }
+    if (!CUSTOM_KEY_REGEX.test(key)) {
+        return 'INVALID_KEY: must start with alphanumeric and contain only alphanumeric, dots, hyphens, underscores, and slashes';
+    }
+    return null;
+}
+/**
+ * Derive an ltree path from a custom S3 key's directory portion.
+ * e.g., "reports/2024/Q1/revenue.pdf" → "reports.2024.Q1"
+ * Returns null if the key has no directory component.
+ */
+function derivePathFromKey(key) {
+    const lastSlash = key.lastIndexOf('/');
+    if (lastSlash <= 0)
+        return null;
+    const dir = key.substring(0, lastSlash);
+    return dir.replace(/\//g, '.');
+}
 /**
  * Resolve the database_id from the JWT context.
  * The server middleware sets jwt.claims.database_id, which is accessible
@@ -128,6 +164,14 @@ export function createPresignedUrlPlugin(options) {
         size: Int!
         """Original filename (optional, for display and Content-Disposition)"""
         filename: String
+        """
+        Custom S3 key (e.g., "reports/2024/Q1.pdf").
+        Only allowed when the bucket has allow_custom_keys=true.
+        When omitted, key defaults to contentHash (content-addressed dedup).
+        When provided, the file is stored at this key.
+        Re-uploading to an existing key auto-creates a new version.
+        """
+        key: String
       }
 
       type RequestUploadUrlPayload {
@@ -141,6 +185,52 @@ export function createPresignedUrlPlugin(options) {
         deduplicated: Boolean!
         """Presigned URL expiry time (null if deduplicated)"""
         expiresAt: Datetime
+        """ID of the previous version (set when re-uploading to an existing custom key)"""
+        previousVersionId: UUID
+      }
+
+      input BulkUploadFileInput {
+        """SHA-256 content hash computed by the client (hex-encoded, 64 chars)"""
+        contentHash: String!
+        """MIME type of the file (e.g., "image/png")"""
+        contentType: String!
+        """File size in bytes"""
+        size: Int!
+        """Original filename (optional, for display and Content-Disposition)"""
+        filename: String
+        """Custom S3 key (only when bucket has allow_custom_keys=true)"""
+        key: String
+      }
+
+      input RequestBulkUploadUrlsInput {
+        """Bucket key (e.g., "public", "private")"""
+        bucketKey: String!
+        """Owner entity ID for entity-scoped uploads"""
+        ownerId: UUID
+        """Array of files to upload"""
+        files: [BulkUploadFileInput!]!
+      }
+
+      type BulkUploadFilePayload {
+        """Presigned PUT URL (null if file was deduplicated)"""
+        uploadUrl: String
+        """The file ID"""
+        fileId: UUID!
+        """The S3 object key"""
+        key: String!
+        """Whether this file was deduplicated"""
+        deduplicated: Boolean!
+        """Presigned URL expiry time (null if deduplicated)"""
+        expiresAt: Datetime
+        """ID of the previous version (set when re-uploading to an existing custom key)"""
+        previousVersionId: UUID
+        """Index of this file in the input array (for client correlation)"""
+        index: Int!
+      }
+
+      type RequestBulkUploadUrlsPayload {
+        """Array of results, one per input file"""
+        files: [BulkUploadFilePayload!]!
       }
 
       extend type Mutation {
@@ -153,6 +243,15 @@ export function createPresignedUrlPlugin(options) {
         requestUploadUrl(
           input: RequestUploadUrlInput!
         ): RequestUploadUrlPayload
+
+        """
+        Request presigned URLs for uploading multiple files in a single batch.
+        Subject to per-storage-module limits (max_bulk_files, max_bulk_total_size).
+        Each file is processed independently — some may dedup while others get fresh URLs.
+        """
+        requestBulkUploadUrls(
+          input: RequestBulkUploadUrlsInput!
+        ): RequestBulkUploadUrlsPayload
       }
     `,
         plans: {
@@ -167,28 +266,33 @@ export function createPresignedUrlPlugin(options) {
                         pgSettings: $pgSettings,
                     });
                     return lambda($combined, async ({ input, withPgClient, pgSettings }) => {
-                        // --- Input validation ---
-                        const { bucketKey, ownerId, contentHash, contentType, size, filename } = input;
+                        const result = await processUpload(options, input, withPgClient, pgSettings);
+                        return result;
+                    });
+                },
+                requestBulkUploadUrls(_$mutation, fieldArgs) {
+                    const $input = fieldArgs.getRaw('input');
+                    const $withPgClient = grafastContext().get('withPgClient');
+                    const $pgSettings = grafastContext().get('pgSettings');
+                    const $combined = object({
+                        input: $input,
+                        withPgClient: $withPgClient,
+                        pgSettings: $pgSettings,
+                    });
+                    return lambda($combined, async ({ input, withPgClient, pgSettings }) => {
+                        const { bucketKey, ownerId, files } = input;
                         if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
                             throw new Error('INVALID_BUCKET_KEY');
                         }
-                        if (!contentHash || typeof contentHash !== 'string' || contentHash.length > MAX_CONTENT_HASH_LENGTH) {
-                            throw new Error('INVALID_CONTENT_HASH');
-                        }
-                        if (!isValidSha256(contentHash)) {
-                            throw new Error('INVALID_CONTENT_HASH_FORMAT: must be a 64-char lowercase hex SHA-256');
-                        }
-                        if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
-                            throw new Error('INVALID_CONTENT_TYPE');
+                        if (!Array.isArray(files) || files.length === 0) {
+                            throw new Error('INVALID_FILES: must provide at least one file');
                         }
                         return withPgClient(pgSettings, async (pgClient) => {
                             return pgClient.withTransaction(async (txClient) => {
-                                // --- Resolve storage module config (all limits come from here) ---
                                 const databaseId = await resolveDatabaseId(txClient);
                                 if (!databaseId) {
                                     throw new Error('DATABASE_NOT_FOUND');
                                 }
-                                // --- Resolve storage module (app-level or entity-scoped) ---
                                 const storageConfig = ownerId
                                     ? await getStorageModuleConfigForOwner(txClient, databaseId, ownerId)
                                     : await getStorageModuleConfig(txClient, databaseId);
@@ -197,107 +301,34 @@ export function createPresignedUrlPlugin(options) {
                                         ? '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) {
-                                    throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
+                                // --- Validate bulk limits ---
+                                if (files.length > storageConfig.maxBulkFiles) {
+                                    throw new Error(`BULK_LIMIT_EXCEEDED: max ${storageConfig.maxBulkFiles} files per batch`);
                                 }
-                                if (filename !== undefined && filename !== null) {
-                                    if (typeof filename !== 'string' || filename.length > storageConfig.maxFilenameLength) {
-                                        throw new Error('INVALID_FILENAME');
-                                    }
+                                const totalSize = files.reduce((sum, f) => sum + (f.size || 0), 0);
+                                if (totalSize > storageConfig.maxBulkTotalSize) {
+                                    throw new Error(`BULK_SIZE_EXCEEDED: total size ${totalSize} exceeds max ${storageConfig.maxBulkTotalSize} bytes`);
                                 }
-                                // --- Look up the bucket (cached; first miss queries via RLS) ---
                                 const bucket = await getBucketConfig(txClient, storageConfig, databaseId, bucketKey, ownerId);
                                 if (!bucket) {
                                     throw new Error('BUCKET_NOT_FOUND');
                                 }
-                                // --- Validate content type against bucket's allowed_mime_types ---
-                                if (bucket.allowed_mime_types && bucket.allowed_mime_types.length > 0) {
-                                    const allowed = bucket.allowed_mime_types;
-                                    const isAllowed = allowed.some((pattern) => {
-                                        if (pattern === '*/*')
-                                            return true;
-                                        if (pattern.endsWith('/*')) {
-                                            const prefix = pattern.slice(0, -1);
-                                            return contentType.startsWith(prefix);
-                                        }
-                                        return contentType === pattern;
-                                    });
-                                    if (!isAllowed) {
-                                        throw new Error(`CONTENT_TYPE_NOT_ALLOWED: ${contentType} not in bucket allowed types`);
-                                    }
-                                }
-                                // --- Validate size against bucket's max_file_size ---
-                                if (bucket.max_file_size && size > bucket.max_file_size) {
-                                    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 key (content hash) in this bucket ---
-                                const dedupResult = await txClient.query({
-                                    text: `SELECT id
-                   FROM ${storageConfig.filesQualifiedName}
-                   WHERE key = $1
-                     AND bucket_id = $2
-                   LIMIT 1`,
-                                    values: [s3Key, bucket.id],
-                                });
-                                if (dedupResult.rows.length > 0) {
-                                    const existingFile = dedupResult.rows[0];
-                                    log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
-                                    return {
-                                        uploadUrl: null,
-                                        fileId: existingFile.id,
-                                        key: s3Key,
-                                        deduplicated: true,
-                                        expiresAt: null,
-                                    };
-                                }
-                                // --- Create file record ---
-                                // 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: hasOwnerColumn
-                                        ? `INSERT INTO ${storageConfig.filesQualifiedName}
-                       (bucket_id, key, mime_type, size, filename, owner_id, is_public)
-                       VALUES ($1, $2, $3, $4, $5, $6, $7)
-                       RETURNING id`
-                                        : `INSERT INTO ${storageConfig.filesQualifiedName}
-                       (bucket_id, key, mime_type, size, filename, is_public)
-                       VALUES ($1, $2, $3, $4, $5, $6)
-                       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) ---
+                                // --- Ensure S3 bucket exists once for the batch ---
                                 const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
                                 await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-                                // --- Generate presigned PUT URL (per-database bucket) ---
-                                const uploadUrl = await generatePresignedPutUrl(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
-                                const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
-                                return {
-                                    uploadUrl,
-                                    fileId,
-                                    key: s3Key,
-                                    deduplicated: false,
-                                    expiresAt,
-                                };
+                                // --- Process each file ---
+                                const results = [];
+                                for (let i = 0; i < files.length; i++) {
+                                    const fileInput = files[i];
+                                    const singleInput = {
+                                        ...fileInput,
+                                        bucketKey,
+                                        ownerId,
+                                    };
+                                    const result = await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, singleInput);
+                                    results.push({ ...result, index: i });
+                                }
+                                return { files: results };
                             });
                         });
                     });
@@ -306,5 +337,212 @@ export function createPresignedUrlPlugin(options) {
         },
     }));
 }
+// --- Shared upload logic ---
+/**
+ * Process a single upload request (used by both requestUploadUrl and requestBulkUploadUrls).
+ */
+async function processUpload(options, input, withPgClient, pgSettings) {
+    const { bucketKey, ownerId, contentHash, contentType, size, filename, key: customKey } = input;
+    if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
+        throw new Error('INVALID_BUCKET_KEY');
+    }
+    if (!contentHash || typeof contentHash !== 'string' || contentHash.length > MAX_CONTENT_HASH_LENGTH) {
+        throw new Error('INVALID_CONTENT_HASH');
+    }
+    if (!isValidSha256(contentHash)) {
+        throw new Error('INVALID_CONTENT_HASH_FORMAT: must be a 64-char lowercase hex SHA-256');
+    }
+    if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
+        throw new Error('INVALID_CONTENT_TYPE');
+    }
+    return withPgClient(pgSettings, async (pgClient) => {
+        return pgClient.withTransaction(async (txClient) => {
+            const databaseId = await resolveDatabaseId(txClient);
+            if (!databaseId) {
+                throw new Error('DATABASE_NOT_FOUND');
+            }
+            const storageConfig = ownerId
+                ? await getStorageModuleConfigForOwner(txClient, databaseId, ownerId)
+                : await getStorageModuleConfig(txClient, databaseId);
+            if (!storageConfig) {
+                throw new Error(ownerId
+                    ? 'STORAGE_MODULE_NOT_FOUND_FOR_OWNER: no storage module found for the given ownerId'
+                    : 'STORAGE_MODULE_NOT_PROVISIONED');
+            }
+            if (typeof size !== 'number' || size <= 0 || size > storageConfig.defaultMaxFileSize) {
+                throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
+            }
+            if (filename !== undefined && filename !== null) {
+                if (typeof filename !== 'string' || filename.length > storageConfig.maxFilenameLength) {
+                    throw new Error('INVALID_FILENAME');
+                }
+            }
+            const bucket = await getBucketConfig(txClient, storageConfig, databaseId, bucketKey, ownerId);
+            if (!bucket) {
+                throw new Error('BUCKET_NOT_FOUND');
+            }
+            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
+            return processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, input);
+        });
+    });
+}
+/**
+ * Process a single file upload within an already-resolved context.
+ * Handles dedup, custom keys, versioning, and auto-path derivation.
+ */
+async function processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, input) {
+    const { contentHash, contentType, size, filename, key: customKey } = input;
+    // --- Validate inputs ---
+    if (!contentHash || !isValidSha256(contentHash)) {
+        throw new Error('INVALID_CONTENT_HASH_FORMAT: must be a 64-char lowercase hex SHA-256');
+    }
+    if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
+        throw new Error('INVALID_CONTENT_TYPE');
+    }
+    if (typeof size !== 'number' || size <= 0 || size > storageConfig.defaultMaxFileSize) {
+        throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
+    }
+    if (filename !== undefined && filename !== null) {
+        if (typeof filename !== 'string' || filename.length > storageConfig.maxFilenameLength) {
+            throw new Error('INVALID_FILENAME');
+        }
+    }
+    // --- Validate content type against bucket's allowed_mime_types ---
+    if (bucket.allowed_mime_types && bucket.allowed_mime_types.length > 0) {
+        const allowed = bucket.allowed_mime_types;
+        const isAllowed = allowed.some((pattern) => {
+            if (pattern === '*/*')
+                return true;
+            if (pattern.endsWith('/*')) {
+                const prefix = pattern.slice(0, -1);
+                return contentType.startsWith(prefix);
+            }
+            return contentType === pattern;
+        });
+        if (!isAllowed) {
+            throw new Error(`CONTENT_TYPE_NOT_ALLOWED: ${contentType} not in bucket allowed types`);
+        }
+    }
+    // --- Validate size against bucket's max_file_size ---
+    if (bucket.max_file_size && size > bucket.max_file_size) {
+        throw new Error(`FILE_TOO_LARGE: exceeds bucket max of ${bucket.max_file_size} bytes`);
+    }
+    // --- Determine S3 key ---
+    let s3Key;
+    let isCustomKey = false;
+    if (customKey) {
+        if (!bucket.allow_custom_keys) {
+            throw new Error('CUSTOM_KEY_NOT_ALLOWED: bucket does not allow custom keys');
+        }
+        const keyError = validateCustomKey(customKey);
+        if (keyError) {
+            throw new Error(keyError);
+        }
+        s3Key = customKey;
+        isCustomKey = true;
+    }
+    else {
+        s3Key = buildS3Key(contentHash);
+    }
+    // --- Dedup / versioning check ---
+    let previousVersionId = null;
+    if (isCustomKey) {
+        // Custom key mode: check if a file with this key already exists in this bucket.
+        // If so, auto-version by linking via previous_version_id.
+        const existingResult = await txClient.query({
+            text: `SELECT id, content_hash
+       FROM ${storageConfig.filesQualifiedName}
+       WHERE key = $1
+         AND bucket_id = $2
+       ORDER BY created_at DESC
+       LIMIT 1`,
+            values: [s3Key, bucket.id],
+        });
+        if (existingResult.rows.length > 0) {
+            const existing = existingResult.rows[0];
+            // Same content hash = true dedup (no new upload needed)
+            if (existing.content_hash === contentHash) {
+                log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
+                return {
+                    uploadUrl: null,
+                    fileId: existing.id,
+                    key: s3Key,
+                    deduplicated: true,
+                    expiresAt: null,
+                    previousVersionId: null,
+                };
+            }
+            // Different content = new version
+            previousVersionId = existing.id;
+            log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
+        }
+    }
+    else {
+        // Hash-based mode: dedup by content_hash in this bucket
+        const dedupResult = await txClient.query({
+            text: `SELECT id
+       FROM ${storageConfig.filesQualifiedName}
+       WHERE content_hash = $1
+         AND bucket_id = $2
+       LIMIT 1`,
+            values: [contentHash, bucket.id],
+        });
+        if (dedupResult.rows.length > 0) {
+            const existingFile = dedupResult.rows[0];
+            log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
+            return {
+                uploadUrl: null,
+                fileId: existingFile.id,
+                key: s3Key,
+                deduplicated: true,
+                expiresAt: null,
+                previousVersionId: null,
+            };
+        }
+    }
+    // --- Auto-derive ltree path from custom key directory (only when has_path_shares) ---
+    const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
+    // --- Create file record ---
+    const hasOwnerColumn = storageConfig.membershipType !== null;
+    const columns = ['bucket_id', 'key', 'content_hash', 'mime_type', 'size', 'filename', 'is_public'];
+    const values = [bucket.id, s3Key, contentHash, contentType, size, filename || null, bucket.is_public];
+    let paramIdx = values.length;
+    if (hasOwnerColumn) {
+        columns.push('owner_id');
+        values.push(bucket.owner_id);
+        paramIdx = values.length;
+    }
+    if (previousVersionId) {
+        columns.push('previous_version_id');
+        values.push(previousVersionId);
+        paramIdx = values.length;
+    }
+    if (derivedPath) {
+        columns.push('path');
+        values.push(derivedPath);
+        paramIdx = values.length;
+    }
+    const placeholders = values.map((_, i) => `$${i + 1}`).join(', ');
+    const fileResult = await txClient.query({
+        text: `INSERT INTO ${storageConfig.filesQualifiedName}
+           (${columns.join(', ')})
+           VALUES (${placeholders})
+           RETURNING id`,
+        values,
+    });
+    const fileId = fileResult.rows[0].id;
+    // --- Generate presigned PUT URL ---
+    const uploadUrl = await generatePresignedPutUrl(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
+    const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
+    return {
+        uploadUrl,
+        fileId,
+        key: s3Key,
+        deduplicated: false,
+        expiresAt,
+        previousVersionId,
+    };
+}
 export const PresignedUrlPlugin = createPresignedUrlPlugin;
 export default PresignedUrlPlugin;

package/esm/storage-module-cache.js

@@ -8,6 +8,8 @@ const DEFAULT_DOWNLOAD_URL_EXPIRY_SECONDS = 3600; // 1 hour
 const DEFAULT_MAX_FILE_SIZE = 200 * 1024 * 1024; // 200MB
 const DEFAULT_MAX_FILENAME_LENGTH = 1024;
 const DEFAULT_CACHE_TTL_SECONDS = process.env.NODE_ENV === 'development' ? 300 : 3600;
+const DEFAULT_MAX_BULK_FILES = 100;
+const DEFAULT_MAX_BULK_TOTAL_SIZE = 1073741824; // 1GB
 const FIVE_MINUTES_MS = 1000 * 60 * 5;
 const ONE_HOUR_MS = 1000 * 60 * 60;
 /**
@@ -51,6 +53,9 @@ const APP_STORAGE_MODULE_QUERY = `
     sm.default_max_file_size,
     sm.max_filename_length,
     sm.cache_ttl_seconds,
+    sm.max_bulk_files,
+    sm.max_bulk_total_size,
+    sm.has_path_shares,
     NULL AS entity_schema,
     NULL AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -86,6 +91,9 @@ const ALL_STORAGE_MODULES_QUERY = `
     sm.default_max_file_size,
     sm.max_filename_length,
     sm.cache_ttl_seconds,
+    sm.max_bulk_files,
+    sm.max_bulk_total_size,
+    sm.has_path_shares,
     es.schema_name AS entity_schema,
     et.name AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -123,6 +131,9 @@ function buildConfig(row) {
         defaultMaxFileSize: row.default_max_file_size ?? DEFAULT_MAX_FILE_SIZE,
         maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
         cacheTtlSeconds,
+        hasPathShares: row.has_path_shares ?? false,
+        maxBulkFiles: row.max_bulk_files ?? DEFAULT_MAX_BULK_FILES,
+        maxBulkTotalSize: row.max_bulk_total_size ?? DEFAULT_MAX_BULK_TOTAL_SIZE,
     };
 }
 /**
@@ -291,11 +302,11 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
     const hasOwner = ownerId && storageConfig.membershipType !== null;
     const result = await pgClient.query({
         text: hasOwner
-            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size
+            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys
          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
+            : `SELECT id, key, type, is_public, ${storageConfig.membershipType !== null ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1
          LIMIT 1`,
@@ -313,6 +324,7 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
         owner_id: row.owner_id ?? null,
         allowed_mime_types: row.allowed_mime_types,
         max_file_size: row.max_file_size,
+        allow_custom_keys: row.allow_custom_keys ?? false,
     };
     bucketCache.set(cacheKey, config);
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.membershipType ?? 'app'})`);

package/esm/types.d.ts

@@ -10,6 +10,7 @@ export interface BucketConfig {
     owner_id: string | null;
     allowed_mime_types: string[] | null;
     max_file_size: number | null;
+    allow_custom_keys: boolean;
 }
 /**
  * Storage module configuration resolved from metaschema for a given database.
@@ -51,6 +52,12 @@ export interface StorageModuleConfig {
     maxFilenameLength: number;
     /** Cache TTL in seconds for this config entry (default: 300 dev / 3600 prod) */
     cacheTtlSeconds: number;
+    /** Whether this storage module uses ltree path + path shares (determines if path column exists on files) */
+    hasPathShares: boolean;
+    /** Max files per requestBulkUploadUrls batch (default: 100) */
+    maxBulkFiles: number;
+    /** Max total size per bulk upload batch in bytes (default: 1GB) */
+    maxBulkTotalSize: number;
 }
 /**
  * Input for the requestUploadUrl mutation.
@@ -73,6 +80,13 @@ export interface RequestUploadUrlInput {
     size: number;
     /** Original filename (optional, for display/Content-Disposition) */
     filename?: string;
+    /**
+     * Custom S3 key for the file (only allowed when bucket has allow_custom_keys=true).
+     * When omitted, key defaults to contentHash (content-addressed dedup).
+     * When provided, the file is stored at this key; dedup is bypassed.
+     * Max 1024 chars. Must not contain path traversal (.. or leading /).
+     */
+    key?: string;
 }
 /**
  * Result of the requestUploadUrl mutation.
@@ -88,6 +102,8 @@ export interface RequestUploadUrlPayload {
     deduplicated: boolean;
     /** Presigned URL expiry time (null if deduplicated) */
     expiresAt: string | null;
+    /** ID of the previous version (set when re-uploading to an existing custom key) */
+    previousVersionId: string | null;
 }
 /**
  * S3 configuration for the presigned URL plugin.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl mutation and downloadUrl computed field",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -42,7 +42,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1009.0",
     "@aws-sdk/s3-request-presigner": "^3.1009.0",
-    "@pgpmjs/logger": "^2.6.0",
+    "@pgpmjs/logger": "^2.7.0",
     "@pgsql/quotes": "^17.1.0",
     "lru-cache": "^11.2.7"
   },
@@ -56,9 +56,9 @@
     "postgraphile": "5.0.0"
   },
   "devDependencies": {
-    "@constructive-io/s3-utils": "^2.12.1",
+    "@constructive-io/s3-utils": "^2.13.0",
     "@types/node": "^22.19.11",
     "makage": "^0.1.10"
   },
-  "gitHead": "0238640b70fed4b203eb84f48315c2bd807923b9"
+  "gitHead": "fb12131bc72ca66e2eb554e15c49e35dc5b362ac"
 }

package/plugin.js

@@ -26,7 +26,9 @@ const log = new logger_1.Logger('graphile-presigned-url:plugin');
 const MAX_CONTENT_HASH_LENGTH = 128;
 const MAX_CONTENT_TYPE_LENGTH = 255;
 const MAX_BUCKET_KEY_LENGTH = 255;
+const MAX_CUSTOM_KEY_LENGTH = 1024;
 const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/;
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_.\-\/]*$/;
 // --- Helpers ---
 /**
  * Validate a SHA-256 hex string.
@@ -35,12 +37,46 @@ function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
 }
 /**
- * Build the S3 key from content hash and content type extension.
+ * Build the S3 key from content hash.
  * Format: {contentHash} (flat namespace, content-addressed)
  */
 function buildS3Key(contentHash) {
     return contentHash;
 }
+/**
+ * Validate a custom S3 key.
+ * Must be 1-1024 chars, no path traversal, no leading slash, no null bytes.
+ */
+function validateCustomKey(key) {
+    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
+        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
+    }
+    if (key.includes('..')) {
+        return 'INVALID_KEY: path traversal (..) not allowed';
+    }
+    if (key.startsWith('/')) {
+        return 'INVALID_KEY: leading slash not allowed';
+    }
+    if (key.includes('\0')) {
+        return 'INVALID_KEY: null bytes not allowed';
+    }
+    if (!CUSTOM_KEY_REGEX.test(key)) {
+        return 'INVALID_KEY: must start with alphanumeric and contain only alphanumeric, dots, hyphens, underscores, and slashes';
+    }
+    return null;
+}
+/**
+ * Derive an ltree path from a custom S3 key's directory portion.
+ * e.g., "reports/2024/Q1/revenue.pdf" → "reports.2024.Q1"
+ * Returns null if the key has no directory component.
+ */
+function derivePathFromKey(key) {
+    const lastSlash = key.lastIndexOf('/');
+    if (lastSlash <= 0)
+        return null;
+    const dir = key.substring(0, lastSlash);
+    return dir.replace(/\//g, '.');
+}
 /**
  * Resolve the database_id from the JWT context.
  * The server middleware sets jwt.claims.database_id, which is accessible
@@ -132,6 +168,14 @@ function createPresignedUrlPlugin(options) {
         size: Int!
         """Original filename (optional, for display and Content-Disposition)"""
         filename: String
+        """
+        Custom S3 key (e.g., "reports/2024/Q1.pdf").
+        Only allowed when the bucket has allow_custom_keys=true.
+        When omitted, key defaults to contentHash (content-addressed dedup).
+        When provided, the file is stored at this key.
+        Re-uploading to an existing key auto-creates a new version.
+        """
+        key: String
       }
 
       type RequestUploadUrlPayload {
@@ -145,6 +189,52 @@ function createPresignedUrlPlugin(options) {
         deduplicated: Boolean!
         """Presigned URL expiry time (null if deduplicated)"""
         expiresAt: Datetime
+        """ID of the previous version (set when re-uploading to an existing custom key)"""
+        previousVersionId: UUID
+      }
+
+      input BulkUploadFileInput {
+        """SHA-256 content hash computed by the client (hex-encoded, 64 chars)"""
+        contentHash: String!
+        """MIME type of the file (e.g., "image/png")"""
+        contentType: String!
+        """File size in bytes"""
+        size: Int!
+        """Original filename (optional, for display and Content-Disposition)"""
+        filename: String
+        """Custom S3 key (only when bucket has allow_custom_keys=true)"""
+        key: String
+      }
+
+      input RequestBulkUploadUrlsInput {
+        """Bucket key (e.g., "public", "private")"""
+        bucketKey: String!
+        """Owner entity ID for entity-scoped uploads"""
+        ownerId: UUID
+        """Array of files to upload"""
+        files: [BulkUploadFileInput!]!
+      }
+
+      type BulkUploadFilePayload {
+        """Presigned PUT URL (null if file was deduplicated)"""
+        uploadUrl: String
+        """The file ID"""
+        fileId: UUID!
+        """The S3 object key"""
+        key: String!
+        """Whether this file was deduplicated"""
+        deduplicated: Boolean!
+        """Presigned URL expiry time (null if deduplicated)"""
+        expiresAt: Datetime
+        """ID of the previous version (set when re-uploading to an existing custom key)"""
+        previousVersionId: UUID
+        """Index of this file in the input array (for client correlation)"""
+        index: Int!
+      }
+
+      type RequestBulkUploadUrlsPayload {
+        """Array of results, one per input file"""
+        files: [BulkUploadFilePayload!]!
       }
 
       extend type Mutation {
@@ -157,6 +247,15 @@ function createPresignedUrlPlugin(options) {
         requestUploadUrl(
           input: RequestUploadUrlInput!
         ): RequestUploadUrlPayload
+
+        """
+        Request presigned URLs for uploading multiple files in a single batch.
+        Subject to per-storage-module limits (max_bulk_files, max_bulk_total_size).
+        Each file is processed independently — some may dedup while others get fresh URLs.
+        """
+        requestBulkUploadUrls(
+          input: RequestBulkUploadUrlsInput!
+        ): RequestBulkUploadUrlsPayload
       }
     `,
         plans: {
@@ -171,28 +270,33 @@ function createPresignedUrlPlugin(options) {
                         pgSettings: $pgSettings,
                     });
                     return (0, grafast_1.lambda)($combined, async ({ input, withPgClient, pgSettings }) => {
-                        // --- Input validation ---
-                        const { bucketKey, ownerId, contentHash, contentType, size, filename } = input;
+                        const result = await processUpload(options, input, withPgClient, pgSettings);
+                        return result;
+                    });
+                },
+                requestBulkUploadUrls(_$mutation, fieldArgs) {
+                    const $input = fieldArgs.getRaw('input');
+                    const $withPgClient = (0, grafast_1.context)().get('withPgClient');
+                    const $pgSettings = (0, grafast_1.context)().get('pgSettings');
+                    const $combined = (0, grafast_1.object)({
+                        input: $input,
+                        withPgClient: $withPgClient,
+                        pgSettings: $pgSettings,
+                    });
+                    return (0, grafast_1.lambda)($combined, async ({ input, withPgClient, pgSettings }) => {
+                        const { bucketKey, ownerId, files } = input;
                         if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
                             throw new Error('INVALID_BUCKET_KEY');
                         }
-                        if (!contentHash || typeof contentHash !== 'string' || contentHash.length > MAX_CONTENT_HASH_LENGTH) {
-                            throw new Error('INVALID_CONTENT_HASH');
-                        }
-                        if (!isValidSha256(contentHash)) {
-                            throw new Error('INVALID_CONTENT_HASH_FORMAT: must be a 64-char lowercase hex SHA-256');
-                        }
-                        if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
-                            throw new Error('INVALID_CONTENT_TYPE');
+                        if (!Array.isArray(files) || files.length === 0) {
+                            throw new Error('INVALID_FILES: must provide at least one file');
                         }
                         return withPgClient(pgSettings, async (pgClient) => {
                             return pgClient.withTransaction(async (txClient) => {
-                                // --- Resolve storage module config (all limits come from here) ---
                                 const databaseId = await resolveDatabaseId(txClient);
                                 if (!databaseId) {
                                     throw new Error('DATABASE_NOT_FOUND');
                                 }
-                                // --- 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);
@@ -201,107 +305,34 @@ function createPresignedUrlPlugin(options) {
                                         ? '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) {
-                                    throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
+                                // --- Validate bulk limits ---
+                                if (files.length > storageConfig.maxBulkFiles) {
+                                    throw new Error(`BULK_LIMIT_EXCEEDED: max ${storageConfig.maxBulkFiles} files per batch`);
                                 }
-                                if (filename !== undefined && filename !== null) {
-                                    if (typeof filename !== 'string' || filename.length > storageConfig.maxFilenameLength) {
-                                        throw new Error('INVALID_FILENAME');
-                                    }
+                                const totalSize = files.reduce((sum, f) => sum + (f.size || 0), 0);
+                                if (totalSize > storageConfig.maxBulkTotalSize) {
+                                    throw new Error(`BULK_SIZE_EXCEEDED: total size ${totalSize} exceeds max ${storageConfig.maxBulkTotalSize} bytes`);
                                 }
-                                // --- Look up the bucket (cached; first miss queries via RLS) ---
                                 const bucket = await (0, storage_module_cache_1.getBucketConfig)(txClient, storageConfig, databaseId, bucketKey, ownerId);
                                 if (!bucket) {
                                     throw new Error('BUCKET_NOT_FOUND');
                                 }
-                                // --- Validate content type against bucket's allowed_mime_types ---
-                                if (bucket.allowed_mime_types && bucket.allowed_mime_types.length > 0) {
-                                    const allowed = bucket.allowed_mime_types;
-                                    const isAllowed = allowed.some((pattern) => {
-                                        if (pattern === '*/*')
-                                            return true;
-                                        if (pattern.endsWith('/*')) {
-                                            const prefix = pattern.slice(0, -1);
-                                            return contentType.startsWith(prefix);
-                                        }
-                                        return contentType === pattern;
-                                    });
-                                    if (!isAllowed) {
-                                        throw new Error(`CONTENT_TYPE_NOT_ALLOWED: ${contentType} not in bucket allowed types`);
-                                    }
-                                }
-                                // --- Validate size against bucket's max_file_size ---
-                                if (bucket.max_file_size && size > bucket.max_file_size) {
-                                    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 key (content hash) in this bucket ---
-                                const dedupResult = await txClient.query({
-                                    text: `SELECT id
-                   FROM ${storageConfig.filesQualifiedName}
-                   WHERE key = $1
-                     AND bucket_id = $2
-                   LIMIT 1`,
-                                    values: [s3Key, bucket.id],
-                                });
-                                if (dedupResult.rows.length > 0) {
-                                    const existingFile = dedupResult.rows[0];
-                                    log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
-                                    return {
-                                        uploadUrl: null,
-                                        fileId: existingFile.id,
-                                        key: s3Key,
-                                        deduplicated: true,
-                                        expiresAt: null,
-                                    };
-                                }
-                                // --- Create file record ---
-                                // 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: hasOwnerColumn
-                                        ? `INSERT INTO ${storageConfig.filesQualifiedName}
-                       (bucket_id, key, mime_type, size, filename, owner_id, is_public)
-                       VALUES ($1, $2, $3, $4, $5, $6, $7)
-                       RETURNING id`
-                                        : `INSERT INTO ${storageConfig.filesQualifiedName}
-                       (bucket_id, key, mime_type, size, filename, is_public)
-                       VALUES ($1, $2, $3, $4, $5, $6)
-                       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) ---
+                                // --- Ensure S3 bucket exists once for the batch ---
                                 const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
                                 await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-                                // --- Generate presigned PUT URL (per-database bucket) ---
-                                const uploadUrl = await (0, s3_signer_1.generatePresignedPutUrl)(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
-                                const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
-                                return {
-                                    uploadUrl,
-                                    fileId,
-                                    key: s3Key,
-                                    deduplicated: false,
-                                    expiresAt,
-                                };
+                                // --- Process each file ---
+                                const results = [];
+                                for (let i = 0; i < files.length; i++) {
+                                    const fileInput = files[i];
+                                    const singleInput = {
+                                        ...fileInput,
+                                        bucketKey,
+                                        ownerId,
+                                    };
+                                    const result = await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, singleInput);
+                                    results.push({ ...result, index: i });
+                                }
+                                return { files: results };
                             });
                         });
                     });
@@ -310,5 +341,212 @@ function createPresignedUrlPlugin(options) {
         },
     }));
 }
+// --- Shared upload logic ---
+/**
+ * Process a single upload request (used by both requestUploadUrl and requestBulkUploadUrls).
+ */
+async function processUpload(options, input, withPgClient, pgSettings) {
+    const { bucketKey, ownerId, contentHash, contentType, size, filename, key: customKey } = input;
+    if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
+        throw new Error('INVALID_BUCKET_KEY');
+    }
+    if (!contentHash || typeof contentHash !== 'string' || contentHash.length > MAX_CONTENT_HASH_LENGTH) {
+        throw new Error('INVALID_CONTENT_HASH');
+    }
+    if (!isValidSha256(contentHash)) {
+        throw new Error('INVALID_CONTENT_HASH_FORMAT: must be a 64-char lowercase hex SHA-256');
+    }
+    if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
+        throw new Error('INVALID_CONTENT_TYPE');
+    }
+    return withPgClient(pgSettings, async (pgClient) => {
+        return pgClient.withTransaction(async (txClient) => {
+            const databaseId = await resolveDatabaseId(txClient);
+            if (!databaseId) {
+                throw new Error('DATABASE_NOT_FOUND');
+            }
+            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(ownerId
+                    ? 'STORAGE_MODULE_NOT_FOUND_FOR_OWNER: no storage module found for the given ownerId'
+                    : 'STORAGE_MODULE_NOT_PROVISIONED');
+            }
+            if (typeof size !== 'number' || size <= 0 || size > storageConfig.defaultMaxFileSize) {
+                throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
+            }
+            if (filename !== undefined && filename !== null) {
+                if (typeof filename !== 'string' || filename.length > storageConfig.maxFilenameLength) {
+                    throw new Error('INVALID_FILENAME');
+                }
+            }
+            const bucket = await (0, storage_module_cache_1.getBucketConfig)(txClient, storageConfig, databaseId, bucketKey, ownerId);
+            if (!bucket) {
+                throw new Error('BUCKET_NOT_FOUND');
+            }
+            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
+            return processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, input);
+        });
+    });
+}
+/**
+ * Process a single file upload within an already-resolved context.
+ * Handles dedup, custom keys, versioning, and auto-path derivation.
+ */
+async function processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, input) {
+    const { contentHash, contentType, size, filename, key: customKey } = input;
+    // --- Validate inputs ---
+    if (!contentHash || !isValidSha256(contentHash)) {
+        throw new Error('INVALID_CONTENT_HASH_FORMAT: must be a 64-char lowercase hex SHA-256');
+    }
+    if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
+        throw new Error('INVALID_CONTENT_TYPE');
+    }
+    if (typeof size !== 'number' || size <= 0 || size > storageConfig.defaultMaxFileSize) {
+        throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
+    }
+    if (filename !== undefined && filename !== null) {
+        if (typeof filename !== 'string' || filename.length > storageConfig.maxFilenameLength) {
+            throw new Error('INVALID_FILENAME');
+        }
+    }
+    // --- Validate content type against bucket's allowed_mime_types ---
+    if (bucket.allowed_mime_types && bucket.allowed_mime_types.length > 0) {
+        const allowed = bucket.allowed_mime_types;
+        const isAllowed = allowed.some((pattern) => {
+            if (pattern === '*/*')
+                return true;
+            if (pattern.endsWith('/*')) {
+                const prefix = pattern.slice(0, -1);
+                return contentType.startsWith(prefix);
+            }
+            return contentType === pattern;
+        });
+        if (!isAllowed) {
+            throw new Error(`CONTENT_TYPE_NOT_ALLOWED: ${contentType} not in bucket allowed types`);
+        }
+    }
+    // --- Validate size against bucket's max_file_size ---
+    if (bucket.max_file_size && size > bucket.max_file_size) {
+        throw new Error(`FILE_TOO_LARGE: exceeds bucket max of ${bucket.max_file_size} bytes`);
+    }
+    // --- Determine S3 key ---
+    let s3Key;
+    let isCustomKey = false;
+    if (customKey) {
+        if (!bucket.allow_custom_keys) {
+            throw new Error('CUSTOM_KEY_NOT_ALLOWED: bucket does not allow custom keys');
+        }
+        const keyError = validateCustomKey(customKey);
+        if (keyError) {
+            throw new Error(keyError);
+        }
+        s3Key = customKey;
+        isCustomKey = true;
+    }
+    else {
+        s3Key = buildS3Key(contentHash);
+    }
+    // --- Dedup / versioning check ---
+    let previousVersionId = null;
+    if (isCustomKey) {
+        // Custom key mode: check if a file with this key already exists in this bucket.
+        // If so, auto-version by linking via previous_version_id.
+        const existingResult = await txClient.query({
+            text: `SELECT id, content_hash
+       FROM ${storageConfig.filesQualifiedName}
+       WHERE key = $1
+         AND bucket_id = $2
+       ORDER BY created_at DESC
+       LIMIT 1`,
+            values: [s3Key, bucket.id],
+        });
+        if (existingResult.rows.length > 0) {
+            const existing = existingResult.rows[0];
+            // Same content hash = true dedup (no new upload needed)
+            if (existing.content_hash === contentHash) {
+                log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
+                return {
+                    uploadUrl: null,
+                    fileId: existing.id,
+                    key: s3Key,
+                    deduplicated: true,
+                    expiresAt: null,
+                    previousVersionId: null,
+                };
+            }
+            // Different content = new version
+            previousVersionId = existing.id;
+            log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
+        }
+    }
+    else {
+        // Hash-based mode: dedup by content_hash in this bucket
+        const dedupResult = await txClient.query({
+            text: `SELECT id
+       FROM ${storageConfig.filesQualifiedName}
+       WHERE content_hash = $1
+         AND bucket_id = $2
+       LIMIT 1`,
+            values: [contentHash, bucket.id],
+        });
+        if (dedupResult.rows.length > 0) {
+            const existingFile = dedupResult.rows[0];
+            log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
+            return {
+                uploadUrl: null,
+                fileId: existingFile.id,
+                key: s3Key,
+                deduplicated: true,
+                expiresAt: null,
+                previousVersionId: null,
+            };
+        }
+    }
+    // --- Auto-derive ltree path from custom key directory (only when has_path_shares) ---
+    const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
+    // --- Create file record ---
+    const hasOwnerColumn = storageConfig.membershipType !== null;
+    const columns = ['bucket_id', 'key', 'content_hash', 'mime_type', 'size', 'filename', 'is_public'];
+    const values = [bucket.id, s3Key, contentHash, contentType, size, filename || null, bucket.is_public];
+    let paramIdx = values.length;
+    if (hasOwnerColumn) {
+        columns.push('owner_id');
+        values.push(bucket.owner_id);
+        paramIdx = values.length;
+    }
+    if (previousVersionId) {
+        columns.push('previous_version_id');
+        values.push(previousVersionId);
+        paramIdx = values.length;
+    }
+    if (derivedPath) {
+        columns.push('path');
+        values.push(derivedPath);
+        paramIdx = values.length;
+    }
+    const placeholders = values.map((_, i) => `$${i + 1}`).join(', ');
+    const fileResult = await txClient.query({
+        text: `INSERT INTO ${storageConfig.filesQualifiedName}
+           (${columns.join(', ')})
+           VALUES (${placeholders})
+           RETURNING id`,
+        values,
+    });
+    const fileId = fileResult.rows[0].id;
+    // --- Generate presigned PUT URL ---
+    const uploadUrl = await (0, s3_signer_1.generatePresignedPutUrl)(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
+    const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
+    return {
+        uploadUrl,
+        fileId,
+        key: s3Key,
+        deduplicated: false,
+        expiresAt,
+        previousVersionId,
+    };
+}
 exports.PresignedUrlPlugin = createPresignedUrlPlugin;
 exports.default = exports.PresignedUrlPlugin;

package/storage-module-cache.js

@@ -18,6 +18,8 @@ const DEFAULT_DOWNLOAD_URL_EXPIRY_SECONDS = 3600; // 1 hour
 const DEFAULT_MAX_FILE_SIZE = 200 * 1024 * 1024; // 200MB
 const DEFAULT_MAX_FILENAME_LENGTH = 1024;
 const DEFAULT_CACHE_TTL_SECONDS = process.env.NODE_ENV === 'development' ? 300 : 3600;
+const DEFAULT_MAX_BULK_FILES = 100;
+const DEFAULT_MAX_BULK_TOTAL_SIZE = 1073741824; // 1GB
 const FIVE_MINUTES_MS = 1000 * 60 * 5;
 const ONE_HOUR_MS = 1000 * 60 * 60;
 /**
@@ -61,6 +63,9 @@ const APP_STORAGE_MODULE_QUERY = `
     sm.default_max_file_size,
     sm.max_filename_length,
     sm.cache_ttl_seconds,
+    sm.max_bulk_files,
+    sm.max_bulk_total_size,
+    sm.has_path_shares,
     NULL AS entity_schema,
     NULL AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -96,6 +101,9 @@ const ALL_STORAGE_MODULES_QUERY = `
     sm.default_max_file_size,
     sm.max_filename_length,
     sm.cache_ttl_seconds,
+    sm.max_bulk_files,
+    sm.max_bulk_total_size,
+    sm.has_path_shares,
     es.schema_name AS entity_schema,
     et.name AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -133,6 +141,9 @@ function buildConfig(row) {
         defaultMaxFileSize: row.default_max_file_size ?? DEFAULT_MAX_FILE_SIZE,
         maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
         cacheTtlSeconds,
+        hasPathShares: row.has_path_shares ?? false,
+        maxBulkFiles: row.max_bulk_files ?? DEFAULT_MAX_BULK_FILES,
+        maxBulkTotalSize: row.max_bulk_total_size ?? DEFAULT_MAX_BULK_TOTAL_SIZE,
     };
 }
 /**
@@ -301,11 +312,11 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
     const hasOwner = ownerId && storageConfig.membershipType !== null;
     const result = await pgClient.query({
         text: hasOwner
-            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size
+            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys
          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
+            : `SELECT id, key, type, is_public, ${storageConfig.membershipType !== null ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1
          LIMIT 1`,
@@ -323,6 +334,7 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
         owner_id: row.owner_id ?? null,
         allowed_mime_types: row.allowed_mime_types,
         max_file_size: row.max_file_size,
+        allow_custom_keys: row.allow_custom_keys ?? false,
     };
     bucketCache.set(cacheKey, config);
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.membershipType ?? 'app'})`);

package/types.d.ts

@@ -10,6 +10,7 @@ export interface BucketConfig {
     owner_id: string | null;
     allowed_mime_types: string[] | null;
     max_file_size: number | null;
+    allow_custom_keys: boolean;
 }
 /**
  * Storage module configuration resolved from metaschema for a given database.
@@ -51,6 +52,12 @@ export interface StorageModuleConfig {
     maxFilenameLength: number;
     /** Cache TTL in seconds for this config entry (default: 300 dev / 3600 prod) */
     cacheTtlSeconds: number;
+    /** Whether this storage module uses ltree path + path shares (determines if path column exists on files) */
+    hasPathShares: boolean;
+    /** Max files per requestBulkUploadUrls batch (default: 100) */
+    maxBulkFiles: number;
+    /** Max total size per bulk upload batch in bytes (default: 1GB) */
+    maxBulkTotalSize: number;
 }
 /**
  * Input for the requestUploadUrl mutation.
@@ -73,6 +80,13 @@ export interface RequestUploadUrlInput {
     size: number;
     /** Original filename (optional, for display/Content-Disposition) */
     filename?: string;
+    /**
+     * Custom S3 key for the file (only allowed when bucket has allow_custom_keys=true).
+     * When omitted, key defaults to contentHash (content-addressed dedup).
+     * When provided, the file is stored at this key; dedup is bypassed.
+     * Max 1024 chars. Must not contain path traversal (.. or leading /).
+     */
+    key?: string;
 }
 /**
  * Result of the requestUploadUrl mutation.
@@ -88,6 +102,8 @@ export interface RequestUploadUrlPayload {
     deduplicated: boolean;
     /** Presigned URL expiry time (null if deduplicated) */
     expiresAt: string | null;
+    /** ID of the previous version (set when re-uploading to an existing custom key) */
+    previousVersionId: string | null;
 }
 /**
  * S3 configuration for the presigned URL plugin.