graphile-presigned-url-plugin 1.9.2 → 1.10.0

package/download-url-field.d.ts

@@ -18,8 +18,8 @@
  * lookups. Since downloadUrl is a computed field (not a real column),
  * the plan() function is required for Grafast to execute the S3 signing.
  */
-import type { GraphileConfig } from 'graphile-config';
 import 'graphile-build';
+import type { GraphileConfig } from 'graphile-config';
 import type { PresignedUrlPluginOptions } from './types';
 export declare function createDownloadUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
 export default createDownloadUrlPlugin;

package/download-url-field.js

@@ -22,8 +22,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDownloadUrlPlugin = createDownloadUrlPlugin;
 require("graphile-build");
-const grafast_1 = require("grafast");
 const logger_1 = require("@pgpmjs/logger");
+const grafast_1 = require("grafast");
 const s3_signer_1 = require("./s3-signer");
 const storage_module_cache_1 = require("./storage-module-cache");
 const log = new logger_1.Logger('graphile-presigned-url:download-url');
@@ -49,21 +49,21 @@ function resolveS3(options) {
     return options.s3;
 }
 /**
- * Build a per-database S3Config by overlaying storage_module overrides
- * onto the global S3Config. Same logic as plugin.ts resolveS3ForDatabase.
+ * Build a per-database S3Config for a *known* physical bucket. `physicalName`
+ * is required — the stored coordinate on the bucket row is the only source;
+ * no name is ever recomputed here. Same logic as plugin.ts resolveS3ForDatabase.
  */
-function resolveS3ForDatabase(options, storageConfig, databaseId, bucketKey) {
+function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
-    const bucket = options.resolveBucketName
-        ? options.resolveBucketName(databaseId, bucketKey)
-        : globalS3.bucket;
-    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
-    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+    const publicUrlPrefix = storageConfig.publicUrlPrefix != null
+        ? storageConfig.publicUrlPrefix
+        : globalS3.publicUrlPrefix;
+    if (physicalName === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
         return globalS3;
     }
     return {
         ...globalS3,
-        bucket,
+        bucket: physicalName,
         ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
     };
 }
@@ -126,25 +126,24 @@ function createDownloadUrlPlugin(options) {
                                             const config = databaseId
                                                 ? (0, storage_module_cache_1.resolveStorageConfigFromCodec)(capturedCodec, await withPgClient(null, (pgClient) => (0, storage_module_cache_1.loadAllStorageModules)(pgClient, databaseId)))
                                                 : null;
-                                            const resolved = config
+                                            const resolved = config && bucketId
                                                 ? await withPgClient(pgSettings, async (pgClient) => {
-                                                    // Look up the bucket key for scoped S3 resolution
-                                                    let bucketKey = 'public';
-                                                    if (bucketId) {
-                                                        const bucketResult = await pgClient.query({
-                                                            text: `SELECT key FROM ${config.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
-                                                            values: [bucketId],
-                                                        });
-                                                        if (bucketResult.rows[0]?.key) {
-                                                            bucketKey = bucketResult.rows[0].key;
-                                                        }
-                                                    }
-                                                    return { config, databaseId, bucketKey };
+                                                    // Look up the stored physical coordinate for scoped S3 resolution
+                                                    const bucketResult = await pgClient.query({
+                                                        text: `SELECT key, physical_name FROM ${config.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
+                                                        values: [bucketId],
+                                                    });
+                                                    const row = bucketResult.rows[0];
+                                                    return row ? { config, physicalName: (0, storage_module_cache_1.storedPhysicalName)(row) } : null;
                                                 })
                                                 : null;
                                             if (resolved) {
+                                                if (resolved.physicalName === null) {
+                                                    // No physical bucket was ever provisioned — no object can exist.
+                                                    return null;
+                                                }
                                                 downloadUrlExpirySeconds = resolved.config.downloadUrlExpirySeconds;
-                                                s3ForDb = resolveS3ForDatabase(options, resolved.config, resolved.databaseId, resolved.bucketKey);
+                                                s3ForDb = resolveS3ForDatabase(options, resolved.config, resolved.physicalName);
                                             }
                                         }
                                     }

package/esm/download-url-field.d.ts

@@ -18,8 +18,8 @@
  * lookups. Since downloadUrl is a computed field (not a real column),
  * the plan() function is required for Grafast to execute the S3 signing.
  */
-import type { GraphileConfig } from 'graphile-config';
 import 'graphile-build';
+import type { GraphileConfig } from 'graphile-config';
 import type { PresignedUrlPluginOptions } from './types';
 export declare function createDownloadUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
 export default createDownloadUrlPlugin;

package/esm/download-url-field.js

@@ -19,10 +19,10 @@
  * the plan() function is required for Grafast to execute the S3 signing.
  */
 import 'graphile-build';
-import { context as grafastContext, lambda, object } from 'grafast';
 import { Logger } from '@pgpmjs/logger';
+import { context as grafastContext, lambda, object } from 'grafast';
 import { generatePresignedGetUrl } from './s3-signer';
-import { loadAllStorageModules, resolveStorageConfigFromCodec } from './storage-module-cache';
+import { loadAllStorageModules, resolveStorageConfigFromCodec, storedPhysicalName } from './storage-module-cache';
 const log = new Logger('graphile-presigned-url:download-url');
 /**
  * Creates the downloadUrl computed field plugin.
@@ -46,21 +46,21 @@ function resolveS3(options) {
     return options.s3;
 }
 /**
- * Build a per-database S3Config by overlaying storage_module overrides
- * onto the global S3Config. Same logic as plugin.ts resolveS3ForDatabase.
+ * Build a per-database S3Config for a *known* physical bucket. `physicalName`
+ * is required — the stored coordinate on the bucket row is the only source;
+ * no name is ever recomputed here. Same logic as plugin.ts resolveS3ForDatabase.
  */
-function resolveS3ForDatabase(options, storageConfig, databaseId, bucketKey) {
+function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
-    const bucket = options.resolveBucketName
-        ? options.resolveBucketName(databaseId, bucketKey)
-        : globalS3.bucket;
-    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
-    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+    const publicUrlPrefix = storageConfig.publicUrlPrefix != null
+        ? storageConfig.publicUrlPrefix
+        : globalS3.publicUrlPrefix;
+    if (physicalName === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
         return globalS3;
     }
     return {
         ...globalS3,
-        bucket,
+        bucket: physicalName,
         ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
     };
 }
@@ -123,25 +123,24 @@ export function createDownloadUrlPlugin(options) {
                                             const config = databaseId
                                                 ? resolveStorageConfigFromCodec(capturedCodec, await withPgClient(null, (pgClient) => loadAllStorageModules(pgClient, databaseId)))
                                                 : null;
-                                            const resolved = config
+                                            const resolved = config && bucketId
                                                 ? await withPgClient(pgSettings, async (pgClient) => {
-                                                    // Look up the bucket key for scoped S3 resolution
-                                                    let bucketKey = 'public';
-                                                    if (bucketId) {
-                                                        const bucketResult = await pgClient.query({
-                                                            text: `SELECT key FROM ${config.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
-                                                            values: [bucketId],
-                                                        });
-                                                        if (bucketResult.rows[0]?.key) {
-                                                            bucketKey = bucketResult.rows[0].key;
-                                                        }
-                                                    }
-                                                    return { config, databaseId, bucketKey };
+                                                    // Look up the stored physical coordinate for scoped S3 resolution
+                                                    const bucketResult = await pgClient.query({
+                                                        text: `SELECT key, physical_name FROM ${config.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
+                                                        values: [bucketId],
+                                                    });
+                                                    const row = bucketResult.rows[0];
+                                                    return row ? { config, physicalName: storedPhysicalName(row) } : null;
                                                 })
                                                 : null;
                                             if (resolved) {
+                                                if (resolved.physicalName === null) {
+                                                    // No physical bucket was ever provisioned — no object can exist.
+                                                    return null;
+                                                }
                                                 downloadUrlExpirySeconds = resolved.config.downloadUrlExpirySeconds;
-                                                s3ForDb = resolveS3ForDatabase(options, resolved.config, resolved.databaseId, resolved.bucketKey);
+                                                s3ForDb = resolveS3ForDatabase(options, resolved.config, resolved.physicalName);
                                             }
                                         }
                                     }

package/esm/index.d.ts

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

package/esm/index.js

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

package/esm/plugin.d.ts

@@ -16,8 +16,8 @@
  * Scope resolution uses the codec's schema/table name matched against
  * cached storage module configs.
  */
-import type { GraphileConfig } from 'graphile-config';
 import 'graphile-build';
+import type { GraphileConfig } from 'graphile-config';
 import type { PresignedUrlPluginOptions } from './types';
 export declare function createPresignedUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
 export declare const PresignedUrlPlugin: typeof createPresignedUrlPlugin;

package/esm/plugin.js

@@ -16,18 +16,18 @@
  * Scope resolution uses the codec's schema/table name matched against
  * cached storage module configs.
  */
-import { access, context as grafastContext, lambda, object } from 'grafast';
 import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
-import { loadAllStorageModules, resolveStorageConfigFromCodec, getBucketConfig, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
-import { generatePresignedPutUrl, deleteS3Object } from './s3-signer';
+import { access, context as grafastContext, lambda, object } from 'grafast';
+import { deleteS3Object, generatePresignedPutUrl } from './s3-signer';
+import { getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, storedPhysicalName } from './storage-module-cache';
 const log = new Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
 const MAX_CONTENT_HASH_LENGTH = 128;
 const MAX_CONTENT_TYPE_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_.\-\/]*$/;
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_.\-/]*$/;
 // --- Helpers ---
 function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
@@ -74,30 +74,72 @@ function resolveS3(options) {
     }
     return options.s3;
 }
-function resolveS3ForDatabase(options, storageConfig, databaseId, bucketKey) {
+/**
+ * Mint the physical S3 bucket name for a logical bucket's first provision.
+ *
+ * This is a naming *policy*, consulted exactly once per bucket — before the
+ * physical bucket exists. Once provisioned, the recorded `physical_name` on
+ * the row is authoritative and this function must not be consulted again.
+ */
+function mintPhysicalBucketName(options, databaseId, bucketKey) {
+    if (options.resolveBucketName) {
+        return options.resolveBucketName(databaseId, bucketKey);
+    }
+    // Single-bucket deployment: the globally configured bucket is the physical bucket.
+    return resolveS3(options).bucket;
+}
+/**
+ * Build the S3 config for a *known* physical bucket. `physicalName` is
+ * required — callers must resolve the coordinate (stored row value, or a
+ * freshly provisioned name) before getting here. No name is ever recomputed.
+ */
+function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
-    const bucket = options.resolveBucketName
-        ? options.resolveBucketName(databaseId, bucketKey)
-        : globalS3.bucket;
-    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
-    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+    const publicUrlPrefix = storageConfig.publicUrlPrefix != null
+        ? storageConfig.publicUrlPrefix
+        : globalS3.publicUrlPrefix;
+    if (physicalName === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
         return globalS3;
     }
     return {
         ...globalS3,
-        bucket,
+        bucket: physicalName,
         ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
     };
 }
-async function ensureS3BucketExists(options, s3BucketName, bucket, databaseId, allowedOrigins) {
-    if (!options.ensureBucketProvisioned)
-        return;
-    if (isS3BucketProvisioned(s3BucketName))
-        return;
-    log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
-    await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
-    markS3BucketProvisioned(s3BucketName);
-    log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
+/**
+ * First provision of a logical bucket: mint a name, create the physical S3
+ * bucket, and record the exact name on the source row. Returns the recorded
+ * physical name.
+ *
+ * Only called when the row has no `physical_name` yet. Afterwards the stored
+ * value is the durable coordinate: route resolution and every later read use
+ * it verbatim; nothing is recomputed.
+ *
+ * The record write runs in the system lane (`withPgClient(null, ...)`) — it is
+ * server bookkeeping, not request data, and anonymous request roles cannot
+ * UPDATE bucket rows under RLS. `bucket` (the cached config) is mutated in place
+ * so subsequent reads observe the recorded name without a DB round-trip.
+ */
+async function provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, allowedOrigins) {
+    const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
+    if (options.ensureBucketProvisioned && !isS3BucketProvisioned(s3BucketName)) {
+        log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
+        await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
+        markS3BucketProvisioned(s3BucketName);
+        log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
+    }
+    // Record the physical coordinate on the source row. The `physical_name IS NULL`
+    // guard keeps this idempotent and race-safe across concurrent first uploads.
+    await withPgClient(null, (client) => client.query({
+        text: `UPDATE ${storageConfig.bucketsQualifiedName}
+             SET physical_name = $1
+             WHERE id = $2 AND physical_name IS NULL`,
+        values: [s3BucketName, bucket.id],
+    }));
+    bucket.physical_name = s3BucketName;
+    log.info(`Recorded physical_name="${s3BucketName}" on bucket ${bucket.id}`);
+    return s3BucketName;
 }
 // --- Plugin factory ---
 export function createPresignedUrlPlugin(options) {
@@ -211,22 +253,24 @@ export function createPresignedUrlPlugin(options) {
                                     const storageConfig = resolveStorageConfigFromCodec(capturedFilesCodec, allConfigs);
                                     if (!storageConfig)
                                         throw new Error('STORAGE_MODULE_NOT_FOUND');
-                                    return vals.withPgClient(vals.pgSettings, async (pgClient) => {
-                                        return pgClient.withTransaction(async (txClient) => {
-                                            const bucket = await getBucketConfig(txClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined);
-                                            if (!bucket)
-                                                throw new Error('BUCKET_NOT_FOUND');
-                                            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId, bucket.key);
-                                            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-                                            return processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
-                                                contentHash: vals.contentHash,
-                                                contentType: vals.contentType,
-                                                size: vals.size,
-                                                filename: vals.filename,
-                                                key: vals.customKey,
-                                            });
-                                        });
-                                    });
+                                    // Bucket config read under the request role (RLS-gated visibility).
+                                    const bucket = await vals.withPgClient(vals.pgSettings, (pgClient) => getBucketConfig(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    if (!bucket)
+                                        throw new Error('BUCKET_NOT_FOUND');
+                                    // First provision mints + records the coordinate; afterwards the
+                                    // stored physical_name is authoritative and nothing is recomputed.
+                                    const physicalName = bucket.physical_name === null
+                                        ? await provisionAndRecordPhysicalBucket(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+                                        : bucket.physical_name;
+                                    const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
+                                    // File row INSERT under the request role (RLS enforced).
+                                    return vals.withPgClient(vals.pgSettings, (pgClient) => pgClient.withTransaction((txClient) => processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
+                                        contentHash: vals.contentHash,
+                                        contentType: vals.contentType,
+                                        size: vals.size,
+                                        filename: vals.filename,
+                                        key: vals.customKey,
+                                    })));
                                 });
                             },
                         });
@@ -300,35 +344,39 @@ export function createPresignedUrlPlugin(options) {
                                     const storageConfig = resolveStorageConfigFromCodec(capturedFilesCodec, allConfigs);
                                     if (!storageConfig)
                                         throw new Error('STORAGE_MODULE_NOT_FOUND');
-                                    return vals.withPgClient(vals.pgSettings, async (pgClient) => {
-                                        return pgClient.withTransaction(async (txClient) => {
-                                            const bucket = await getBucketConfig(txClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined);
-                                            if (!bucket)
-                                                throw new Error('BUCKET_NOT_FOUND');
-                                            // Enforce bulk upload limits
-                                            const filesArray = vals.files;
-                                            if (filesArray.length > storageConfig.maxBulkFiles) {
-                                                throw new Error(`BULK_UPLOAD_FILES_EXCEEDED: ${filesArray.length} files exceeds maximum of ${storageConfig.maxBulkFiles} per batch`);
-                                            }
-                                            const totalSize = filesArray.reduce((sum, f) => sum + (f.size || 0), 0);
-                                            if (totalSize > storageConfig.maxBulkTotalSize) {
-                                                throw new Error(`BULK_UPLOAD_SIZE_EXCEEDED: ${totalSize} bytes exceeds maximum of ${storageConfig.maxBulkTotalSize} bytes per batch`);
-                                            }
-                                            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId, bucket.key);
-                                            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-                                            const results = [];
-                                            for (const file of filesArray) {
-                                                results.push(await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
-                                                    contentHash: file.contentHash,
-                                                    contentType: file.contentType,
-                                                    size: file.size,
-                                                    filename: file.filename,
-                                                    key: file.key,
-                                                }));
-                                            }
-                                            return { files: results };
-                                        });
-                                    });
+                                    // Bucket config read under the request role (RLS-gated visibility).
+                                    const bucket = await vals.withPgClient(vals.pgSettings, (pgClient) => getBucketConfig(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    if (!bucket)
+                                        throw new Error('BUCKET_NOT_FOUND');
+                                    // Enforce bulk upload limits
+                                    const filesArray = vals.files;
+                                    if (filesArray.length > storageConfig.maxBulkFiles) {
+                                        throw new Error(`BULK_UPLOAD_FILES_EXCEEDED: ${filesArray.length} files exceeds maximum of ${storageConfig.maxBulkFiles} per batch`);
+                                    }
+                                    const totalSize = filesArray.reduce((sum, f) => sum + (f.size || 0), 0);
+                                    if (totalSize > storageConfig.maxBulkTotalSize) {
+                                        throw new Error(`BULK_UPLOAD_SIZE_EXCEEDED: ${totalSize} bytes exceeds maximum of ${storageConfig.maxBulkTotalSize} bytes per batch`);
+                                    }
+                                    // First provision mints + records the coordinate; afterwards the
+                                    // stored physical_name is authoritative and nothing is recomputed.
+                                    const physicalName = bucket.physical_name === null
+                                        ? await provisionAndRecordPhysicalBucket(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+                                        : bucket.physical_name;
+                                    const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
+                                    // File row INSERTs under the request role (RLS enforced).
+                                    return vals.withPgClient(vals.pgSettings, (pgClient) => pgClient.withTransaction(async (txClient) => {
+                                        const results = [];
+                                        for (const file of filesArray) {
+                                            results.push(await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
+                                                contentHash: file.contentHash,
+                                                contentType: file.contentType,
+                                                size: file.size,
+                                                filename: file.filename,
+                                                key: file.key,
+                                            }));
+                                        }
+                                        return { files: results };
+                                    }));
                                 });
                             },
                         });
@@ -425,18 +473,25 @@ export function createPresignedUrlPlugin(options) {
                                                     log.info(`File deleted from DB; S3 key ${fileRow.key} still referenced by ${refCount} file(s)`);
                                                     return;
                                                 }
-                                                // No other references — attempt sync S3 delete
-                                                // Look up the bucket key for scoped S3 resolution
+                                                // No other references — attempt sync S3 delete.
+                                                // Read the stored physical coordinate; the object lives in the
+                                                // recorded bucket, never a recomputed prefix name.
                                                 const bucketResult = await pgClient.query({
-                                                    text: `SELECT key FROM ${storageConfig.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
+                                                    text: `SELECT key, physical_name FROM ${storageConfig.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
                                                     values: [fileRow.bucket_id],
                                                 });
-                                                const bucketKey = bucketResult.rows[0]?.key;
-                                                if (!bucketKey) {
+                                                const bucketRow = bucketResult.rows[0];
+                                                if (!bucketRow) {
                                                     log.warn(`Bucket not found for bucket_id=${fileRow.bucket_id}; skipping S3 delete`);
                                                     return;
                                                 }
-                                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId, bucketKey);
+                                                const physicalName = storedPhysicalName(bucketRow);
+                                                if (physicalName === null) {
+                                                    // No physical bucket was ever provisioned — there is no object to delete.
+                                                    log.warn(`Bucket ${fileRow.bucket_id} has no physical_name; skipping S3 delete`);
+                                                    return;
+                                                }
+                                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
                                                 await deleteS3Object(s3ForDb, fileRow.key);
                                                 log.info(`Sync S3 delete succeeded for key=${fileRow.key}`);
                                             });

package/esm/preset.js

@@ -5,8 +5,8 @@
  * in PostGraphile. Combines the main mutation plugin (requestUploadUrl)
  * with the downloadUrl computed field plugin.
  */
-import { createPresignedUrlPlugin } from './plugin';
 import { createDownloadUrlPlugin } from './download-url-field';
+import { createPresignedUrlPlugin } from './plugin';
 /**
  * Creates a preset that includes the presigned URL plugins with the given options.
  *

package/esm/s3-signer.js

@@ -1,4 +1,4 @@
-import { PutObjectCommand, GetObjectCommand, HeadObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { Logger } from '@pgpmjs/logger';
 const log = new Logger('graphile-presigned-url:s3');

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

@@ -1,4 +1,4 @@
-import type { StorageModuleConfig, BucketConfig } from './types';
+import type { BucketConfig, StorageModuleConfig } from './types';
 /**
  * Resolve the app-level storage module config for a database, using the LRU cache.
  *
@@ -100,6 +100,17 @@ export declare function resolveStorageConfigFromCodec(pgCodec: {
     };
     sqlType?: string;
 }, allConfigs: StorageModuleConfig[]): StorageModuleConfig | null;
+/**
+ * Normalize the recorded physical coordinate at the DB boundary.
+ *
+ * A bucket row either carries a recorded coordinate or it does not; SQL nulls
+ * and absent columns both mean "never provisioned". Collapsing them here is
+ * the single place that shape is interpreted — callers branch on `string`
+ * vs `null` and never coalesce a bucket name into existence.
+ */
+export declare function storedPhysicalName(row: {
+    physical_name?: string | null;
+}): string | null;
 /**
  * Resolve bucket metadata for a given database + bucket key, using the LRU cache.
  *

package/esm/storage-module-cache.js

@@ -1,6 +1,6 @@
 import { Logger } from '@pgpmjs/logger';
-import { LRUCache } from 'lru-cache';
 import { QuoteUtils } from '@pgsql/quotes';
+import { LRUCache } from 'lru-cache';
 const log = new Logger('graphile-presigned-url:cache');
 // --- Defaults ---
 const DEFAULT_UPLOAD_URL_EXPIRY_SECONDS = 900; // 15 minutes
@@ -320,6 +320,17 @@ const bucketCache = new LRUCache({
     ttl: process.env.NODE_ENV === 'development' ? FIVE_MINUTES_MS : ONE_HOUR_MS,
     updateAgeOnGet: true,
 });
+/**
+ * Normalize the recorded physical coordinate at the DB boundary.
+ *
+ * A bucket row either carries a recorded coordinate or it does not; SQL nulls
+ * and absent columns both mean "never provisioned". Collapsing them here is
+ * the single place that shape is interpreted — callers branch on `string`
+ * vs `null` and never coalesce a bucket name into existence.
+ */
+export function storedPhysicalName(row) {
+    return row.physical_name == null ? null : row.physical_name;
+}
 /**
  * Resolve bucket metadata for a given database + bucket key, using the LRU cache.
  *
@@ -346,11 +357,11 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
     const hasOwner = ownerId && isEntityScoped;
     const result = await pgClient.query({
         text: hasOwner
-            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys
+            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys, physical_name
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1 AND owner_id = $2
          LIMIT 1`
-            : `SELECT id, key, type, is_public, ${isEntityScoped ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
+            : `SELECT id, key, type, is_public, ${isEntityScoped ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys, physical_name
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1
          LIMIT 1`,
@@ -369,6 +380,7 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
         allowed_mime_types: row.allowed_mime_types,
         max_file_size: row.max_file_size,
         allow_custom_keys: row.allow_custom_keys ?? false,
+        physical_name: storedPhysicalName(row),
     };
     bucketCache.set(cacheKey, config);
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.scope})`);

package/esm/types.d.ts

@@ -11,6 +11,13 @@ export interface BucketConfig {
     allowed_mime_types: string[] | null;
     max_file_size: number | null;
     allow_custom_keys: boolean;
+    /**
+     * The physical S3/MinIO bucket name recorded when the physical bucket was
+     * first provisioned. NULL until the first upload provisions it. Once set,
+     * it is the source of truth for the physical bucket — reads never
+     * reconstruct the name from a prefix convention.
+     */
+    physical_name: string | null;
 }
 /**
  * Storage module configuration resolved from metaschema for a given database.

package/index.d.ts

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

package/index.js

@@ -28,27 +28,27 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.headObject = exports.deleteS3Object = exports.generatePresignedGetUrl = exports.generatePresignedPutUrl = exports.markS3BucketProvisioned = exports.isS3BucketProvisioned = exports.clearBucketCache = exports.clearStorageModuleCache = exports.resolveStorageConfigFromCodec = exports.loadAllStorageModules = 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; } });
+exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getStorageModuleConfigForOwner = exports.getStorageModuleConfig = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.createDownloadUrlPlugin = void 0;
 var download_url_field_1 = require("./download-url-field");
 Object.defineProperty(exports, "createDownloadUrlPlugin", { enumerable: true, get: function () { return download_url_field_1.createDownloadUrlPlugin; } });
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "createPresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.createPresignedUrlPlugin; } });
+Object.defineProperty(exports, "PresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.PresignedUrlPlugin; } });
 var preset_1 = require("./preset");
 Object.defineProperty(exports, "PresignedUrlPreset", { enumerable: true, get: function () { return preset_1.PresignedUrlPreset; } });
+var s3_signer_1 = require("./s3-signer");
+Object.defineProperty(exports, "deleteS3Object", { enumerable: true, get: function () { return s3_signer_1.deleteS3Object; } });
+Object.defineProperty(exports, "generatePresignedGetUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedGetUrl; } });
+Object.defineProperty(exports, "generatePresignedPutUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedPutUrl; } });
+Object.defineProperty(exports, "headObject", { enumerable: true, get: function () { return s3_signer_1.headObject; } });
 var storage_module_cache_1 = require("./storage-module-cache");
+Object.defineProperty(exports, "clearBucketCache", { enumerable: true, get: function () { return storage_module_cache_1.clearBucketCache; } });
+Object.defineProperty(exports, "clearStorageModuleCache", { enumerable: true, get: function () { return storage_module_cache_1.clearStorageModuleCache; } });
+Object.defineProperty(exports, "getBucketConfig", { enumerable: true, get: function () { return storage_module_cache_1.getBucketConfig; } });
 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, "loadAllStorageModules", { enumerable: true, get: function () { return storage_module_cache_1.loadAllStorageModules; } });
-Object.defineProperty(exports, "resolveStorageConfigFromCodec", { enumerable: true, get: function () { return storage_module_cache_1.resolveStorageConfigFromCodec; } });
-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; } });
+Object.defineProperty(exports, "loadAllStorageModules", { enumerable: true, get: function () { return storage_module_cache_1.loadAllStorageModules; } });
 Object.defineProperty(exports, "markS3BucketProvisioned", { enumerable: true, get: function () { return storage_module_cache_1.markS3BucketProvisioned; } });
-var s3_signer_1 = require("./s3-signer");
-Object.defineProperty(exports, "generatePresignedPutUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedPutUrl; } });
-Object.defineProperty(exports, "generatePresignedGetUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedGetUrl; } });
-Object.defineProperty(exports, "deleteS3Object", { enumerable: true, get: function () { return s3_signer_1.deleteS3Object; } });
-Object.defineProperty(exports, "headObject", { enumerable: true, get: function () { return s3_signer_1.headObject; } });
+Object.defineProperty(exports, "resolveStorageConfigFromCodec", { enumerable: true, get: function () { return storage_module_cache_1.resolveStorageConfigFromCodec; } });
+Object.defineProperty(exports, "resolveStorageModuleByFileId", { enumerable: true, get: function () { return storage_module_cache_1.resolveStorageModuleByFileId; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.9.2",
+  "version": "1.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,8 +42,8 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1052.0",
     "@aws-sdk/s3-request-presigner": "^3.1052.0",
-    "@pgpmjs/logger": "^2.23.2",
-    "@pgsql/quotes": "^18.1.0",
+    "@pgpmjs/logger": "^2.23.3",
+    "@pgsql/quotes": "^18.2.0",
     "lru-cache": "^11.2.7"
   },
   "peerDependencies": {
@@ -56,9 +56,9 @@
     "postgraphile": "5.0.3"
   },
   "devDependencies": {
-    "@constructive-io/s3-utils": "^2.29.2",
+    "@constructive-io/s3-utils": "^2.29.3",
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "90f447482b056a4949134565db2665f21d11aca3"
+  "gitHead": "c438821362ceaf70b2a20d74ecf25ad4191c1748"
 }

package/plugin.d.ts

@@ -16,8 +16,8 @@
  * Scope resolution uses the codec's schema/table name matched against
  * cached storage module configs.
  */
-import type { GraphileConfig } from 'graphile-config';
 import 'graphile-build';
+import type { GraphileConfig } from 'graphile-config';
 import type { PresignedUrlPluginOptions } from './types';
 export declare function createPresignedUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
 export declare const PresignedUrlPlugin: typeof createPresignedUrlPlugin;

package/plugin.js

@@ -20,18 +20,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PresignedUrlPlugin = void 0;
 exports.createPresignedUrlPlugin = createPresignedUrlPlugin;
-const grafast_1 = require("grafast");
 require("graphile-build");
 const logger_1 = require("@pgpmjs/logger");
-const storage_module_cache_1 = require("./storage-module-cache");
+const grafast_1 = require("grafast");
 const s3_signer_1 = require("./s3-signer");
+const storage_module_cache_1 = require("./storage-module-cache");
 const log = new logger_1.Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
 const MAX_CONTENT_HASH_LENGTH = 128;
 const MAX_CONTENT_TYPE_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_.\-\/]*$/;
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_.\-/]*$/;
 // --- Helpers ---
 function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
@@ -78,30 +78,72 @@ function resolveS3(options) {
     }
     return options.s3;
 }
-function resolveS3ForDatabase(options, storageConfig, databaseId, bucketKey) {
+/**
+ * Mint the physical S3 bucket name for a logical bucket's first provision.
+ *
+ * This is a naming *policy*, consulted exactly once per bucket — before the
+ * physical bucket exists. Once provisioned, the recorded `physical_name` on
+ * the row is authoritative and this function must not be consulted again.
+ */
+function mintPhysicalBucketName(options, databaseId, bucketKey) {
+    if (options.resolveBucketName) {
+        return options.resolveBucketName(databaseId, bucketKey);
+    }
+    // Single-bucket deployment: the globally configured bucket is the physical bucket.
+    return resolveS3(options).bucket;
+}
+/**
+ * Build the S3 config for a *known* physical bucket. `physicalName` is
+ * required — callers must resolve the coordinate (stored row value, or a
+ * freshly provisioned name) before getting here. No name is ever recomputed.
+ */
+function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
-    const bucket = options.resolveBucketName
-        ? options.resolveBucketName(databaseId, bucketKey)
-        : globalS3.bucket;
-    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
-    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+    const publicUrlPrefix = storageConfig.publicUrlPrefix != null
+        ? storageConfig.publicUrlPrefix
+        : globalS3.publicUrlPrefix;
+    if (physicalName === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
         return globalS3;
     }
     return {
         ...globalS3,
-        bucket,
+        bucket: physicalName,
         ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
     };
 }
-async function ensureS3BucketExists(options, s3BucketName, bucket, databaseId, allowedOrigins) {
-    if (!options.ensureBucketProvisioned)
-        return;
-    if ((0, storage_module_cache_1.isS3BucketProvisioned)(s3BucketName))
-        return;
-    log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
-    await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
-    (0, storage_module_cache_1.markS3BucketProvisioned)(s3BucketName);
-    log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
+/**
+ * First provision of a logical bucket: mint a name, create the physical S3
+ * bucket, and record the exact name on the source row. Returns the recorded
+ * physical name.
+ *
+ * Only called when the row has no `physical_name` yet. Afterwards the stored
+ * value is the durable coordinate: route resolution and every later read use
+ * it verbatim; nothing is recomputed.
+ *
+ * The record write runs in the system lane (`withPgClient(null, ...)`) — it is
+ * server bookkeeping, not request data, and anonymous request roles cannot
+ * UPDATE bucket rows under RLS. `bucket` (the cached config) is mutated in place
+ * so subsequent reads observe the recorded name without a DB round-trip.
+ */
+async function provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, allowedOrigins) {
+    const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
+    if (options.ensureBucketProvisioned && !(0, storage_module_cache_1.isS3BucketProvisioned)(s3BucketName)) {
+        log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
+        await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
+        (0, storage_module_cache_1.markS3BucketProvisioned)(s3BucketName);
+        log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
+    }
+    // Record the physical coordinate on the source row. The `physical_name IS NULL`
+    // guard keeps this idempotent and race-safe across concurrent first uploads.
+    await withPgClient(null, (client) => client.query({
+        text: `UPDATE ${storageConfig.bucketsQualifiedName}
+             SET physical_name = $1
+             WHERE id = $2 AND physical_name IS NULL`,
+        values: [s3BucketName, bucket.id],
+    }));
+    bucket.physical_name = s3BucketName;
+    log.info(`Recorded physical_name="${s3BucketName}" on bucket ${bucket.id}`);
+    return s3BucketName;
 }
 // --- Plugin factory ---
 function createPresignedUrlPlugin(options) {
@@ -215,22 +257,24 @@ function createPresignedUrlPlugin(options) {
                                     const storageConfig = (0, storage_module_cache_1.resolveStorageConfigFromCodec)(capturedFilesCodec, allConfigs);
                                     if (!storageConfig)
                                         throw new Error('STORAGE_MODULE_NOT_FOUND');
-                                    return vals.withPgClient(vals.pgSettings, async (pgClient) => {
-                                        return pgClient.withTransaction(async (txClient) => {
-                                            const bucket = await (0, storage_module_cache_1.getBucketConfig)(txClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined);
-                                            if (!bucket)
-                                                throw new Error('BUCKET_NOT_FOUND');
-                                            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId, bucket.key);
-                                            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-                                            return processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
-                                                contentHash: vals.contentHash,
-                                                contentType: vals.contentType,
-                                                size: vals.size,
-                                                filename: vals.filename,
-                                                key: vals.customKey,
-                                            });
-                                        });
-                                    });
+                                    // Bucket config read under the request role (RLS-gated visibility).
+                                    const bucket = await vals.withPgClient(vals.pgSettings, (pgClient) => (0, storage_module_cache_1.getBucketConfig)(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    if (!bucket)
+                                        throw new Error('BUCKET_NOT_FOUND');
+                                    // First provision mints + records the coordinate; afterwards the
+                                    // stored physical_name is authoritative and nothing is recomputed.
+                                    const physicalName = bucket.physical_name === null
+                                        ? await provisionAndRecordPhysicalBucket(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+                                        : bucket.physical_name;
+                                    const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
+                                    // File row INSERT under the request role (RLS enforced).
+                                    return vals.withPgClient(vals.pgSettings, (pgClient) => pgClient.withTransaction((txClient) => processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
+                                        contentHash: vals.contentHash,
+                                        contentType: vals.contentType,
+                                        size: vals.size,
+                                        filename: vals.filename,
+                                        key: vals.customKey,
+                                    })));
                                 });
                             },
                         });
@@ -304,35 +348,39 @@ function createPresignedUrlPlugin(options) {
                                     const storageConfig = (0, storage_module_cache_1.resolveStorageConfigFromCodec)(capturedFilesCodec, allConfigs);
                                     if (!storageConfig)
                                         throw new Error('STORAGE_MODULE_NOT_FOUND');
-                                    return vals.withPgClient(vals.pgSettings, async (pgClient) => {
-                                        return pgClient.withTransaction(async (txClient) => {
-                                            const bucket = await (0, storage_module_cache_1.getBucketConfig)(txClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined);
-                                            if (!bucket)
-                                                throw new Error('BUCKET_NOT_FOUND');
-                                            // Enforce bulk upload limits
-                                            const filesArray = vals.files;
-                                            if (filesArray.length > storageConfig.maxBulkFiles) {
-                                                throw new Error(`BULK_UPLOAD_FILES_EXCEEDED: ${filesArray.length} files exceeds maximum of ${storageConfig.maxBulkFiles} per batch`);
-                                            }
-                                            const totalSize = filesArray.reduce((sum, f) => sum + (f.size || 0), 0);
-                                            if (totalSize > storageConfig.maxBulkTotalSize) {
-                                                throw new Error(`BULK_UPLOAD_SIZE_EXCEEDED: ${totalSize} bytes exceeds maximum of ${storageConfig.maxBulkTotalSize} bytes per batch`);
-                                            }
-                                            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId, bucket.key);
-                                            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-                                            const results = [];
-                                            for (const file of filesArray) {
-                                                results.push(await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
-                                                    contentHash: file.contentHash,
-                                                    contentType: file.contentType,
-                                                    size: file.size,
-                                                    filename: file.filename,
-                                                    key: file.key,
-                                                }));
-                                            }
-                                            return { files: results };
-                                        });
-                                    });
+                                    // Bucket config read under the request role (RLS-gated visibility).
+                                    const bucket = await vals.withPgClient(vals.pgSettings, (pgClient) => (0, storage_module_cache_1.getBucketConfig)(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    if (!bucket)
+                                        throw new Error('BUCKET_NOT_FOUND');
+                                    // Enforce bulk upload limits
+                                    const filesArray = vals.files;
+                                    if (filesArray.length > storageConfig.maxBulkFiles) {
+                                        throw new Error(`BULK_UPLOAD_FILES_EXCEEDED: ${filesArray.length} files exceeds maximum of ${storageConfig.maxBulkFiles} per batch`);
+                                    }
+                                    const totalSize = filesArray.reduce((sum, f) => sum + (f.size || 0), 0);
+                                    if (totalSize > storageConfig.maxBulkTotalSize) {
+                                        throw new Error(`BULK_UPLOAD_SIZE_EXCEEDED: ${totalSize} bytes exceeds maximum of ${storageConfig.maxBulkTotalSize} bytes per batch`);
+                                    }
+                                    // First provision mints + records the coordinate; afterwards the
+                                    // stored physical_name is authoritative and nothing is recomputed.
+                                    const physicalName = bucket.physical_name === null
+                                        ? await provisionAndRecordPhysicalBucket(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+                                        : bucket.physical_name;
+                                    const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
+                                    // File row INSERTs under the request role (RLS enforced).
+                                    return vals.withPgClient(vals.pgSettings, (pgClient) => pgClient.withTransaction(async (txClient) => {
+                                        const results = [];
+                                        for (const file of filesArray) {
+                                            results.push(await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
+                                                contentHash: file.contentHash,
+                                                contentType: file.contentType,
+                                                size: file.size,
+                                                filename: file.filename,
+                                                key: file.key,
+                                            }));
+                                        }
+                                        return { files: results };
+                                    }));
                                 });
                             },
                         });
@@ -429,18 +477,25 @@ function createPresignedUrlPlugin(options) {
                                                     log.info(`File deleted from DB; S3 key ${fileRow.key} still referenced by ${refCount} file(s)`);
                                                     return;
                                                 }
-                                                // No other references — attempt sync S3 delete
-                                                // Look up the bucket key for scoped S3 resolution
+                                                // No other references — attempt sync S3 delete.
+                                                // Read the stored physical coordinate; the object lives in the
+                                                // recorded bucket, never a recomputed prefix name.
                                                 const bucketResult = await pgClient.query({
-                                                    text: `SELECT key FROM ${storageConfig.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
+                                                    text: `SELECT key, physical_name FROM ${storageConfig.bucketsQualifiedName} WHERE id = $1 LIMIT 1`,
                                                     values: [fileRow.bucket_id],
                                                 });
-                                                const bucketKey = bucketResult.rows[0]?.key;
-                                                if (!bucketKey) {
+                                                const bucketRow = bucketResult.rows[0];
+                                                if (!bucketRow) {
                                                     log.warn(`Bucket not found for bucket_id=${fileRow.bucket_id}; skipping S3 delete`);
                                                     return;
                                                 }
-                                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId, bucketKey);
+                                                const physicalName = (0, storage_module_cache_1.storedPhysicalName)(bucketRow);
+                                                if (physicalName === null) {
+                                                    // No physical bucket was ever provisioned — there is no object to delete.
+                                                    log.warn(`Bucket ${fileRow.bucket_id} has no physical_name; skipping S3 delete`);
+                                                    return;
+                                                }
+                                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
                                                 await (0, s3_signer_1.deleteS3Object)(s3ForDb, fileRow.key);
                                                 log.info(`Sync S3 delete succeeded for key=${fileRow.key}`);
                                             });

package/preset.js

@@ -8,8 +8,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PresignedUrlPreset = PresignedUrlPreset;
-const plugin_1 = require("./plugin");
 const download_url_field_1 = require("./download-url-field");
+const plugin_1 = require("./plugin");
 /**
  * Creates a preset that includes the presigned URL plugins with the given options.
  *

package/storage-module-cache.d.ts

@@ -1,4 +1,4 @@
-import type { StorageModuleConfig, BucketConfig } from './types';
+import type { BucketConfig, StorageModuleConfig } from './types';
 /**
  * Resolve the app-level storage module config for a database, using the LRU cache.
  *
@@ -100,6 +100,17 @@ export declare function resolveStorageConfigFromCodec(pgCodec: {
     };
     sqlType?: string;
 }, allConfigs: StorageModuleConfig[]): StorageModuleConfig | null;
+/**
+ * Normalize the recorded physical coordinate at the DB boundary.
+ *
+ * A bucket row either carries a recorded coordinate or it does not; SQL nulls
+ * and absent columns both mean "never provisioned". Collapsing them here is
+ * the single place that shape is interpreted — callers branch on `string`
+ * vs `null` and never coalesce a bucket name into existence.
+ */
+export declare function storedPhysicalName(row: {
+    physical_name?: string | null;
+}): string | null;
 /**
  * Resolve bucket metadata for a given database + bucket key, using the LRU cache.
  *

package/storage-module-cache.js

@@ -5,14 +5,15 @@ exports.getStorageModuleConfigForOwner = getStorageModuleConfigForOwner;
 exports.resolveStorageModuleByFileId = resolveStorageModuleByFileId;
 exports.loadAllStorageModules = loadAllStorageModules;
 exports.resolveStorageConfigFromCodec = resolveStorageConfigFromCodec;
+exports.storedPhysicalName = storedPhysicalName;
 exports.getBucketConfig = getBucketConfig;
 exports.isS3BucketProvisioned = isS3BucketProvisioned;
 exports.markS3BucketProvisioned = markS3BucketProvisioned;
 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 lru_cache_1 = require("lru-cache");
 const log = new logger_1.Logger('graphile-presigned-url:cache');
 // --- Defaults ---
 const DEFAULT_UPLOAD_URL_EXPIRY_SECONDS = 900; // 15 minutes
@@ -332,6 +333,17 @@ const bucketCache = new lru_cache_1.LRUCache({
     ttl: process.env.NODE_ENV === 'development' ? FIVE_MINUTES_MS : ONE_HOUR_MS,
     updateAgeOnGet: true,
 });
+/**
+ * Normalize the recorded physical coordinate at the DB boundary.
+ *
+ * A bucket row either carries a recorded coordinate or it does not; SQL nulls
+ * and absent columns both mean "never provisioned". Collapsing them here is
+ * the single place that shape is interpreted — callers branch on `string`
+ * vs `null` and never coalesce a bucket name into existence.
+ */
+function storedPhysicalName(row) {
+    return row.physical_name == null ? null : row.physical_name;
+}
 /**
  * Resolve bucket metadata for a given database + bucket key, using the LRU cache.
  *
@@ -358,11 +370,11 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
     const hasOwner = ownerId && isEntityScoped;
     const result = await pgClient.query({
         text: hasOwner
-            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys
+            ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys, physical_name
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1 AND owner_id = $2
          LIMIT 1`
-            : `SELECT id, key, type, is_public, ${isEntityScoped ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
+            : `SELECT id, key, type, is_public, ${isEntityScoped ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys, physical_name
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1
          LIMIT 1`,
@@ -381,6 +393,7 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
         allowed_mime_types: row.allowed_mime_types,
         max_file_size: row.max_file_size,
         allow_custom_keys: row.allow_custom_keys ?? false,
+        physical_name: storedPhysicalName(row),
     };
     bucketCache.set(cacheKey, config);
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.scope})`);

package/types.d.ts

@@ -11,6 +11,13 @@ export interface BucketConfig {
     allowed_mime_types: string[] | null;
     max_file_size: number | null;
     allow_custom_keys: boolean;
+    /**
+     * The physical S3/MinIO bucket name recorded when the physical bucket was
+     * first provisioned. NULL until the first upload provisions it. Once set,
+     * it is the source of truth for the physical bucket — reads never
+     * reconstruct the name from a prefix convention.
+     */
+    physical_name: string | null;
 }
 /**
  * Storage module configuration resolved from metaschema for a given database.