graphile-presigned-url-plugin 1.9.3 → 1.11.0

package/download-url-field.js

@@ -24,6 +24,7 @@ exports.createDownloadUrlPlugin = createDownloadUrlPlugin;
 require("graphile-build");
 const logger_1 = require("@pgpmjs/logger");
 const grafast_1 = require("grafast");
+const request_pg_client_1 = require("./request-pg-client");
 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 +50,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 } : {}),
     };
 }
@@ -115,7 +116,7 @@ function createDownloadUrlPlugin(options) {
                                     let downloadUrlExpirySeconds = 3600;
                                     try {
                                         if (withPgClient && pgSettings) {
-                                            const databaseId = await withPgClient(pgSettings, async (pgClient) => {
+                                            const databaseId = await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, async (pgClient) => {
                                                 const dbResult = await pgClient.query({
                                                     text: `SELECT jwt_private.current_database_id() AS id`,
                                                 });
@@ -126,25 +127,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
-                                                ? 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 };
+                                            const resolved = config && bucketId
+                                                ? await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, async (pgClient) => {
+                                                    // 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.js

@@ -21,8 +21,9 @@
 import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
 import { context as grafastContext, lambda, object } from 'grafast';
+import { withRequestPgClient } from './request-pg-client';
 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 +47,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 } : {}),
     };
 }
@@ -112,7 +113,7 @@ export function createDownloadUrlPlugin(options) {
                                     let downloadUrlExpirySeconds = 3600;
                                     try {
                                         if (withPgClient && pgSettings) {
-                                            const databaseId = await withPgClient(pgSettings, async (pgClient) => {
+                                            const databaseId = await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
                                                 const dbResult = await pgClient.query({
                                                     text: `SELECT jwt_private.current_database_id() AS id`,
                                                 });
@@ -123,25 +124,24 @@ export function createDownloadUrlPlugin(options) {
                                             const config = databaseId
                                                 ? resolveStorageConfigFromCodec(capturedCodec, await withPgClient(null, (pgClient) => loadAllStorageModules(pgClient, databaseId)))
                                                 : null;
-                                            const resolved = config
-                                                ? 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 };
+                                            const resolved = config && bucketId
+                                                ? await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
+                                                    // 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/plugin.js

@@ -19,8 +19,9 @@
 import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
 import { access, context as grafastContext, lambda, object } from 'grafast';
+import { withRequestPgClient } from './request-pg-client';
 import { deleteS3Object, generatePresignedPutUrl } from './s3-signer';
-import { getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec } from './storage-module-cache';
+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;
@@ -74,30 +75,79 @@ 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 (privileged role, so it bypasses the
+ * RLS that stops request roles from UPDATE-ing bucket rows) — it is server
+ * bookkeeping, not request data. It still carries the tenant `database_id`
+ * claim, because the buckets table's catalog-sync trigger calls
+ * `jwt_private.current_database_id()` and would otherwise raise
+ * DATABASE_CLAIM_REQUIRED; `withRequestPgClient` applies that claim inside the
+ * write's transaction without switching off the privileged role.
+ * `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.
+    // The catalog-sync trigger on this UPDATE needs `jwt.claims.database_id`, so the
+    // write runs under the resolved database claim (privileged role preserved).
+    await withRequestPgClient(withPgClient, { 'jwt.claims.database_id': databaseId }, (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) {
@@ -202,7 +252,10 @@ export function createPresignedUrlPlugin(options) {
                                     pgSettings: $pgSettings,
                                 });
                                 return lambda($combined, async (vals) => {
-                                    const databaseId = await vals.withPgClient(vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                    // Request-lane reads/writes run under the request role's pgSettings
+                                    // inside an explicit transaction so the jwt claims stay applied
+                                    // across every statement (see withRequestPgClient).
+                                    const databaseId = await withRequestPgClient(vals.withPgClient, vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                     if (!databaseId)
                                         throw new Error('DATABASE_NOT_FOUND');
                                     // Module registration is server config, not user data:
@@ -211,22 +264,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 withRequestPgClient(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 withRequestPgClient(vals.withPgClient, vals.pgSettings, (txClient) => processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
+                                        contentHash: vals.contentHash,
+                                        contentType: vals.contentType,
+                                        size: vals.size,
+                                        filename: vals.filename,
+                                        key: vals.customKey,
+                                    }));
                                 });
                             },
                         });
@@ -291,7 +346,10 @@ export function createPresignedUrlPlugin(options) {
                                     pgSettings: $pgSettings,
                                 });
                                 return lambda($combined, async (vals) => {
-                                    const databaseId = await vals.withPgClient(vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                    // Request-lane reads/writes run under the request role's pgSettings
+                                    // inside an explicit transaction so the jwt claims stay applied
+                                    // across every statement (see withRequestPgClient).
+                                    const databaseId = await withRequestPgClient(vals.withPgClient, vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                     if (!databaseId)
                                         throw new Error('DATABASE_NOT_FOUND');
                                     // Module registration is server config, not user data:
@@ -300,34 +358,38 @@ 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 withRequestPgClient(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 withRequestPgClient(vals.withPgClient, vals.pgSettings, 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 };
                                     });
                                 });
                             },
@@ -373,7 +435,7 @@ export function createPresignedUrlPlugin(options) {
                                 const pgSettings = graphqlContext.pgSettings;
                                 if (withPgClient) {
                                     try {
-                                        const databaseId = await withPgClient(pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                        const databaseId = await withRequestPgClient(withPgClient, pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                         // Module registration is server config, not user data:
                                         // resolve it without the request role's pgSettings.
                                         const allConfigs = databaseId
@@ -381,7 +443,7 @@ export function createPresignedUrlPlugin(options) {
                                             : [];
                                         const storageConfig = resolveStorageConfigFromCodec(capturedCodec, allConfigs);
                                         if (storageConfig) {
-                                            await withPgClient(pgSettings, async (pgClient) => {
+                                            await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
                                                 // Read the file row (RLS enforced)
                                                 const result = await pgClient.query({
                                                     text: `SELECT key, bucket_id FROM ${storageConfig.filesQualifiedName} WHERE id = $1 LIMIT 1`,
@@ -406,7 +468,7 @@ export function createPresignedUrlPlugin(options) {
                                 const pgSettings = graphqlContext.pgSettings;
                                 if (withPgClient) {
                                     try {
-                                        const databaseId = await withPgClient(pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                        const databaseId = await withRequestPgClient(withPgClient, pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                         // Module registration is server config, not user data:
                                         // resolve it without the request role's pgSettings.
                                         const allConfigs = databaseId
@@ -414,7 +476,7 @@ export function createPresignedUrlPlugin(options) {
                                             : [];
                                         const storageConfig = resolveStorageConfigFromCodec(capturedCodec, allConfigs);
                                         if (storageConfig)
-                                            await withPgClient(pgSettings, async (pgClient) => {
+                                            await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
                                                 // Check refcount: any other file with the same key in this bucket?
                                                 const refResult = await pgClient.query({
                                                     text: `SELECT COUNT(*)::int AS ref_count FROM ${storageConfig.filesQualifiedName} WHERE key = $1 AND bucket_id = $2`,
@@ -425,18 +487,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/request-pg-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Run a callback under the request's pgSettings inside ONE explicit transaction.
+ *
+ * The grafast context's `withPgClient(pgSettings, cb)` applies pgSettings as
+ * transaction-LOCAL `set_config(key, value, is_local => true)`. When `cb` issues
+ * more than one statement WITHOUT an explicit surrounding transaction, each
+ * statement runs in its own implicit (autocommit) transaction, so a LOCAL
+ * setting applied for one statement is already gone by the next. The request
+ * role's jwt claims (notably `jwt.claims.database_id`) then vanish between
+ * statements, and `jwt_private.current_database_id()` raises
+ * DATABASE_CLAIM_REQUIRED even though the request carried the claim.
+ *
+ * This helper acquires the client without settings (`withPgClient(null, ...)`),
+ * opens a single explicit transaction, and applies the request settings inside
+ * it — so every statement in `cb` observes the same role and jwt claims. It
+ * mirrors the `pg-query-context` pattern used elsewhere in the codebase for
+ * manual, multi-statement RLS work.
+ */
+export interface RequestPgClient {
+    query(opts: {
+        text: string;
+        values?: unknown[];
+    }): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+    withTransaction<T>(cb: (tx: RequestPgClient) => Promise<T>): Promise<T>;
+}
+export type WithPgClient = <T>(pgSettings: Record<string, string> | null, cb: (client: RequestPgClient) => Promise<T>) => Promise<T>;
+export declare function withRequestPgClient<T>(withPgClient: WithPgClient, pgSettings: Record<string, string> | null, cb: (tx: RequestPgClient) => Promise<T>): Promise<T>;

package/esm/request-pg-client.js

@@ -0,0 +1,37 @@
+/**
+ * Run a callback under the request's pgSettings inside ONE explicit transaction.
+ *
+ * The grafast context's `withPgClient(pgSettings, cb)` applies pgSettings as
+ * transaction-LOCAL `set_config(key, value, is_local => true)`. When `cb` issues
+ * more than one statement WITHOUT an explicit surrounding transaction, each
+ * statement runs in its own implicit (autocommit) transaction, so a LOCAL
+ * setting applied for one statement is already gone by the next. The request
+ * role's jwt claims (notably `jwt.claims.database_id`) then vanish between
+ * statements, and `jwt_private.current_database_id()` raises
+ * DATABASE_CLAIM_REQUIRED even though the request carried the claim.
+ *
+ * This helper acquires the client without settings (`withPgClient(null, ...)`),
+ * opens a single explicit transaction, and applies the request settings inside
+ * it — so every statement in `cb` observes the same role and jwt claims. It
+ * mirrors the `pg-query-context` pattern used elsewhere in the codebase for
+ * manual, multi-statement RLS work.
+ */
+async function applyRequestSettings(tx, pgSettings) {
+    if (!pgSettings)
+        return;
+    const entries = Object.entries(pgSettings)
+        .filter(([, value]) => value != null)
+        .map(([key, value]) => [key, String(value)]);
+    if (entries.length === 0)
+        return;
+    await tx.query({
+        text: 'SELECT set_config(el->>0, el->>1, true) FROM json_array_elements($1::json) el',
+        values: [JSON.stringify(entries)],
+    });
+}
+export function withRequestPgClient(withPgClient, pgSettings, cb) {
+    return withPgClient(null, (client) => client.withTransaction(async (tx) => {
+        await applyRequestSettings(tx, pgSettings);
+        return cb(tx);
+    }));
+}

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

@@ -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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.9.3",
+  "version": "1.11.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.1052.0",
     "@aws-sdk/s3-request-presigner": "^3.1052.0",
-    "@pgpmjs/logger": "^2.23.3",
+    "@pgpmjs/logger": "^2.24.0",
     "@pgsql/quotes": "^18.2.0",
     "lru-cache": "^11.2.7"
   },
@@ -56,9 +56,9 @@
     "postgraphile": "5.0.3"
   },
   "devDependencies": {
-    "@constructive-io/s3-utils": "^2.29.3",
+    "@constructive-io/s3-utils": "^2.30.0",
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "c20b6be96b39bf71c0e2df0f4b51e05deacd006b"
+  "gitHead": "d508453a32a2f1d70ff6916871046615226e6f33"
 }

package/plugin.js

@@ -23,6 +23,7 @@ exports.createPresignedUrlPlugin = createPresignedUrlPlugin;
 require("graphile-build");
 const logger_1 = require("@pgpmjs/logger");
 const grafast_1 = require("grafast");
+const request_pg_client_1 = require("./request-pg-client");
 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');
@@ -78,30 +79,79 @@ 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 (privileged role, so it bypasses the
+ * RLS that stops request roles from UPDATE-ing bucket rows) — it is server
+ * bookkeeping, not request data. It still carries the tenant `database_id`
+ * claim, because the buckets table's catalog-sync trigger calls
+ * `jwt_private.current_database_id()` and would otherwise raise
+ * DATABASE_CLAIM_REQUIRED; `withRequestPgClient` applies that claim inside the
+ * write's transaction without switching off the privileged role.
+ * `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.
+    // The catalog-sync trigger on this UPDATE needs `jwt.claims.database_id`, so the
+    // write runs under the resolved database claim (privileged role preserved).
+    await (0, request_pg_client_1.withRequestPgClient)(withPgClient, { 'jwt.claims.database_id': databaseId }, (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) {
@@ -206,7 +256,10 @@ function createPresignedUrlPlugin(options) {
                                     pgSettings: $pgSettings,
                                 });
                                 return (0, grafast_1.lambda)($combined, async (vals) => {
-                                    const databaseId = await vals.withPgClient(vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                    // Request-lane reads/writes run under the request role's pgSettings
+                                    // inside an explicit transaction so the jwt claims stay applied
+                                    // across every statement (see withRequestPgClient).
+                                    const databaseId = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                     if (!databaseId)
                                         throw new Error('DATABASE_NOT_FOUND');
                                     // Module registration is server config, not user data:
@@ -215,22 +268,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 (0, request_pg_client_1.withRequestPgClient)(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 (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (txClient) => processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
+                                        contentHash: vals.contentHash,
+                                        contentType: vals.contentType,
+                                        size: vals.size,
+                                        filename: vals.filename,
+                                        key: vals.customKey,
+                                    }));
                                 });
                             },
                         });
@@ -295,7 +350,10 @@ function createPresignedUrlPlugin(options) {
                                     pgSettings: $pgSettings,
                                 });
                                 return (0, grafast_1.lambda)($combined, async (vals) => {
-                                    const databaseId = await vals.withPgClient(vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                    // Request-lane reads/writes run under the request role's pgSettings
+                                    // inside an explicit transaction so the jwt claims stay applied
+                                    // across every statement (see withRequestPgClient).
+                                    const databaseId = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                     if (!databaseId)
                                         throw new Error('DATABASE_NOT_FOUND');
                                     // Module registration is server config, not user data:
@@ -304,34 +362,38 @@ 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 (0, request_pg_client_1.withRequestPgClient)(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 (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, 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 };
                                     });
                                 });
                             },
@@ -377,7 +439,7 @@ function createPresignedUrlPlugin(options) {
                                 const pgSettings = graphqlContext.pgSettings;
                                 if (withPgClient) {
                                     try {
-                                        const databaseId = await withPgClient(pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                        const databaseId = await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                         // Module registration is server config, not user data:
                                         // resolve it without the request role's pgSettings.
                                         const allConfigs = databaseId
@@ -385,7 +447,7 @@ function createPresignedUrlPlugin(options) {
                                             : [];
                                         const storageConfig = (0, storage_module_cache_1.resolveStorageConfigFromCodec)(capturedCodec, allConfigs);
                                         if (storageConfig) {
-                                            await withPgClient(pgSettings, async (pgClient) => {
+                                            await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, async (pgClient) => {
                                                 // Read the file row (RLS enforced)
                                                 const result = await pgClient.query({
                                                     text: `SELECT key, bucket_id FROM ${storageConfig.filesQualifiedName} WHERE id = $1 LIMIT 1`,
@@ -410,7 +472,7 @@ function createPresignedUrlPlugin(options) {
                                 const pgSettings = graphqlContext.pgSettings;
                                 if (withPgClient) {
                                     try {
-                                        const databaseId = await withPgClient(pgSettings, (pgClient) => resolveDatabaseId(pgClient));
+                                        const databaseId = await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, (pgClient) => resolveDatabaseId(pgClient));
                                         // Module registration is server config, not user data:
                                         // resolve it without the request role's pgSettings.
                                         const allConfigs = databaseId
@@ -418,7 +480,7 @@ function createPresignedUrlPlugin(options) {
                                             : [];
                                         const storageConfig = (0, storage_module_cache_1.resolveStorageConfigFromCodec)(capturedCodec, allConfigs);
                                         if (storageConfig)
-                                            await withPgClient(pgSettings, async (pgClient) => {
+                                            await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, async (pgClient) => {
                                                 // Check refcount: any other file with the same key in this bucket?
                                                 const refResult = await pgClient.query({
                                                     text: `SELECT COUNT(*)::int AS ref_count FROM ${storageConfig.filesQualifiedName} WHERE key = $1 AND bucket_id = $2`,
@@ -429,18 +491,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/request-pg-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Run a callback under the request's pgSettings inside ONE explicit transaction.
+ *
+ * The grafast context's `withPgClient(pgSettings, cb)` applies pgSettings as
+ * transaction-LOCAL `set_config(key, value, is_local => true)`. When `cb` issues
+ * more than one statement WITHOUT an explicit surrounding transaction, each
+ * statement runs in its own implicit (autocommit) transaction, so a LOCAL
+ * setting applied for one statement is already gone by the next. The request
+ * role's jwt claims (notably `jwt.claims.database_id`) then vanish between
+ * statements, and `jwt_private.current_database_id()` raises
+ * DATABASE_CLAIM_REQUIRED even though the request carried the claim.
+ *
+ * This helper acquires the client without settings (`withPgClient(null, ...)`),
+ * opens a single explicit transaction, and applies the request settings inside
+ * it — so every statement in `cb` observes the same role and jwt claims. It
+ * mirrors the `pg-query-context` pattern used elsewhere in the codebase for
+ * manual, multi-statement RLS work.
+ */
+export interface RequestPgClient {
+    query(opts: {
+        text: string;
+        values?: unknown[];
+    }): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+    withTransaction<T>(cb: (tx: RequestPgClient) => Promise<T>): Promise<T>;
+}
+export type WithPgClient = <T>(pgSettings: Record<string, string> | null, cb: (client: RequestPgClient) => Promise<T>) => Promise<T>;
+export declare function withRequestPgClient<T>(withPgClient: WithPgClient, pgSettings: Record<string, string> | null, cb: (tx: RequestPgClient) => Promise<T>): Promise<T>;

package/request-pg-client.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Run a callback under the request's pgSettings inside ONE explicit transaction.
+ *
+ * The grafast context's `withPgClient(pgSettings, cb)` applies pgSettings as
+ * transaction-LOCAL `set_config(key, value, is_local => true)`. When `cb` issues
+ * more than one statement WITHOUT an explicit surrounding transaction, each
+ * statement runs in its own implicit (autocommit) transaction, so a LOCAL
+ * setting applied for one statement is already gone by the next. The request
+ * role's jwt claims (notably `jwt.claims.database_id`) then vanish between
+ * statements, and `jwt_private.current_database_id()` raises
+ * DATABASE_CLAIM_REQUIRED even though the request carried the claim.
+ *
+ * This helper acquires the client without settings (`withPgClient(null, ...)`),
+ * opens a single explicit transaction, and applies the request settings inside
+ * it — so every statement in `cb` observes the same role and jwt claims. It
+ * mirrors the `pg-query-context` pattern used elsewhere in the codebase for
+ * manual, multi-statement RLS work.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRequestPgClient = withRequestPgClient;
+async function applyRequestSettings(tx, pgSettings) {
+    if (!pgSettings)
+        return;
+    const entries = Object.entries(pgSettings)
+        .filter(([, value]) => value != null)
+        .map(([key, value]) => [key, String(value)]);
+    if (entries.length === 0)
+        return;
+    await tx.query({
+        text: 'SELECT set_config(el->>0, el->>1, true) FROM json_array_elements($1::json) el',
+        values: [JSON.stringify(entries)],
+    });
+}
+function withRequestPgClient(withPgClient, pgSettings, cb) {
+    return withPgClient(null, (client) => client.withTransaction(async (tx) => {
+        await applyRequestSettings(tx, pgSettings);
+        return cb(tx);
+    }));
+}

package/storage-module-cache.d.ts

@@ -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,6 +5,7 @@ exports.getStorageModuleConfigForOwner = getStorageModuleConfigForOwner;
 exports.resolveStorageModuleByFileId = resolveStorageModuleByFileId;
 exports.loadAllStorageModules = loadAllStorageModules;
 exports.resolveStorageConfigFromCodec = resolveStorageConfigFromCodec;
+exports.storedPhysicalName = storedPhysicalName;
 exports.getBucketConfig = getBucketConfig;
 exports.isS3BucketProvisioned = isS3BucketProvisioned;
 exports.markS3BucketProvisioned = markS3BucketProvisioned;
@@ -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.