graphile-presigned-url-plugin 1.17.0 → 1.18.0

package/esm/index.d.ts

@@ -34,11 +34,11 @@ export { createDownloadUrlPlugin } from './download-url-field';
 export type { FileRefFieldBinding } from './file-ref-registry';
 export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
 export { assertUploadAllowedByBucket, buildFileProjection, type FileProjection, finalizeStagedUpload, type ManagedUploadTarget, resolveManagedUploadTarget, } from './managed-upload';
-export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, resolveS3ForDatabase } from './physical-bucket';
+export { assertBucketReconciled, resolveS3, resolveS3ForDatabase, StorageBucketNotReconciledError, } from './physical-bucket';
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { type WithPgClient, withRequestPgClient } from './request-pg-client';
 export { describeS3Failure, s3FailureError } from './s3-failure';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
-export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
-export type { BucketConfig, BucketNameResolver, EnsureBucketProvisioned, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';
+export { clearBucketCache, clearStorageModuleCache, getBucketConfig, loadAllStorageModules, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
+export type { BucketConfig, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';

package/esm/index.js

@@ -32,10 +32,10 @@ export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
 export { assertUploadAllowedByBucket, buildFileProjection, finalizeStagedUpload, resolveManagedUploadTarget, } from './managed-upload';
-export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, resolveS3ForDatabase } from './physical-bucket';
+export { assertBucketReconciled, resolveS3, resolveS3ForDatabase, StorageBucketNotReconciledError, } from './physical-bucket';
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { withRequestPgClient } from './request-pg-client';
 export { describeS3Failure, s3FailureError } from './s3-failure';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
-export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
+export { clearBucketCache, clearStorageModuleCache, getBucketConfig, loadAllStorageModules, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';

package/esm/managed-upload.js

@@ -21,7 +21,7 @@ import { Logger } from '@pgpmjs/logger';
 import { resolveDefaultBucket } from './default-bucket';
 import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { getFileRefFieldBinding } from './file-ref-registry';
-import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
+import { assertBucketReconciled, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
 import { copyS3Object, deleteS3Object } from './s3-signer';
 import { recordManagedFile } from './storage-file-recorder';
@@ -134,9 +134,7 @@ export async function resolveManagedUploadTarget(args) {
             'the multipart upload lane only writes content-addressed keys. Use the presigned upload ' +
             'mutation with an explicit key.');
     }
-    const physicalName = bucket.physical_name === null
-        ? await provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-        : bucket.physical_name;
+    const physicalName = assertBucketReconciled(bucket, databaseId);
     return {
         databaseId,
         storageConfig,

package/esm/physical-bucket.d.ts

@@ -1,15 +1,21 @@
 /**
- * Physical bucket coordinates: minting a name once, recording it, and building
- * an S3 config against a *known* name.
+ * Physical bucket coordinates: reading the reconciler's recorded name and
+ * building an S3 config against that known name.
  *
  * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
- * mapping is recorded on the bucket row the first time it is provisioned, and
- * from then on the recorded value is the only coordinate anything reads — no
- * name is ever recomputed from a prefix convention, and there is no
- * environment-level bucket standing in for a tenant's.
+ * mapping is recorded on the bucket row by the storage reconciler, and that
+ * value is the only coordinate anything reads — no name is ever recomputed.
  */
-import { type WithPgClient } from './request-pg-client';
 import type { BucketConfig, PresignedUrlPluginOptions, S3Config, StorageModuleConfig } from './types';
+export declare class StorageBucketNotReconciledError extends Error {
+    readonly code = "STORAGE_BUCKET_NOT_RECONCILED";
+    readonly retryable = true;
+    readonly extensions: {
+        code: string;
+        retryable: boolean;
+    };
+    constructor(bucket: BucketConfig, databaseId: string);
+}
 /**
  * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
  * a lazy getter on first use.
@@ -19,42 +25,14 @@ import type { BucketConfig, PresignedUrlPluginOptions, S3Config, StorageModuleCo
  * resolves its physical bucket from the tenant's bucket row.
  */
 export declare function resolveS3(options: PresignedUrlPluginOptions): S3Config;
-/**
- * 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.
- *
- * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
- * name is not a tenant's storage, and silently minting one is how objects ended
- * up in a bucket no database owned. A deployment that wants per-tenant buckets
- * must supply the policy.
- */
-export declare function mintPhysicalBucketName(options: PresignedUrlPluginOptions, databaseId: string, bucketKey: string): string;
 /**
  * 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.
+ * required — callers must resolve the coordinate from the stored row value
+ * before getting here. No name is ever recomputed.
  */
 export declare function resolveS3ForDatabase(options: PresignedUrlPluginOptions, storageConfig: StorageModuleConfig, physicalName: string): S3Config;
 /**
- * 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.
+ * Return the reconciler's recorded physical name, or fail with a typed,
+ * retryable error while reconciliation is still pending.
  */
-export declare function provisionAndRecordPhysicalBucket(options: PresignedUrlPluginOptions, withPgClient: WithPgClient, storageConfig: StorageModuleConfig, databaseId: string, bucket: BucketConfig, allowedOrigins: string[] | null): Promise<string>;
+export declare function assertBucketReconciled(bucket: BucketConfig, databaseId: string): string;

package/esm/physical-bucket.js

@@ -1,19 +1,25 @@
 /**
- * Physical bucket coordinates: minting a name once, recording it, and building
- * an S3 config against a *known* name.
+ * Physical bucket coordinates: reading the reconciler's recorded name and
+ * building an S3 config against that known name.
  *
  * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
- * mapping is recorded on the bucket row the first time it is provisioned, and
- * from then on the recorded value is the only coordinate anything reads — no
- * name is ever recomputed from a prefix convention, and there is no
- * environment-level bucket standing in for a tenant's.
+ * mapping is recorded on the bucket row by the storage reconciler, and that
+ * value is the only coordinate anything reads — no name is ever recomputed.
  */
-import { Logger } from '@pgpmjs/logger';
-import { recordPhysicalName } from 'graphile-storage-registry';
-import { withRequestPgClient } from './request-pg-client';
-import { s3FailureError } from './s3-failure';
-import { isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
-const log = new Logger('graphile-presigned-url:physical-bucket');
+export class StorageBucketNotReconciledError extends Error {
+    code = 'STORAGE_BUCKET_NOT_RECONCILED';
+    retryable = true;
+    extensions = {
+        code: 'STORAGE_BUCKET_NOT_RECONCILED',
+        retryable: true,
+    };
+    constructor(bucket, databaseId) {
+        super(`STORAGE_BUCKET_NOT_RECONCILED: bucket "${bucket.key}" (id=${bucket.id}) ` +
+            `for database ${databaseId} has not yet been reconciled; the reconciler has ` +
+            'not yet recorded a physical name');
+        this.name = 'StorageBucketNotReconciledError';
+    }
+}
 /**
  * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
  * a lazy getter on first use.
@@ -30,31 +36,10 @@ export function resolveS3(options) {
     }
     return options.s3;
 }
-/**
- * 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.
- *
- * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
- * name is not a tenant's storage, and silently minting one is how objects ended
- * up in a bucket no database owned. A deployment that wants per-tenant buckets
- * must supply the policy.
- */
-export function mintPhysicalBucketName(options, databaseId, bucketKey) {
-    if (!options.resolveBucketName) {
-        throw new Error('STORAGE_BUCKET_NAME_POLICY_MISSING: no resolveBucketName was configured, so there is ' +
-            `no name to provision for bucket "${bucketKey}" of database ${databaseId}. ` +
-            'Physical bucket naming is a deployment policy; the configured s3.bucket is a ' +
-            'connection default and is never a tenant bucket.');
-    }
-    return options.resolveBucketName(databaseId, bucketKey);
-}
 /**
  * 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.
+ * required — callers must resolve the coordinate from the stored row value
+ * before getting here. No name is ever recomputed.
  */
 export function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
@@ -71,46 +56,11 @@ export function resolveS3ForDatabase(options, storageConfig, physicalName) {
     };
 }
 /**
- * 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.
+ * Return the reconciler's recorded physical name, or fail with a typed,
+ * retryable error while reconciliation is still pending.
  */
-export 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}`);
-        try {
-            await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
-        }
-        catch (err) {
-            // The first upload to a bucket is where an unreachable object store is
-            // discovered, and the transport's own message is routinely empty: name the
-            // endpoint it could not reach so the response says what is misconfigured.
-            throw s3FailureError('BUCKET_PROVISION_FAILED', { endpoint: resolveS3(options).endpoint, bucket: s3BucketName, databaseId }, err);
-        }
-        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) => recordPhysicalName((query) => client.query(query), storageConfig.bucketsQualifiedName, bucket.id, s3BucketName));
-    bucket.physical_name = s3BucketName;
-    log.info(`Recorded physical_name="${s3BucketName}" on bucket ${bucket.id}`);
-    return s3BucketName;
+export function assertBucketReconciled(bucket, databaseId) {
+    if (bucket.physical_name !== null)
+        return bucket.physical_name;
+    throw new StorageBucketNotReconciledError(bucket, databaseId);
 }

package/esm/plugin.js

@@ -27,7 +27,7 @@ import { validateCustomKey } from './custom-key';
 import { resolveDefaultBucket } from './default-bucket';
 import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { buildFileProjection } from './managed-upload';
-import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
+import { assertBucketReconciled, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
 import { deleteS3Object, generatePresignedPutUrl } from './s3-signer';
 import { recordManagedFile } from './storage-file-recorder';
@@ -199,11 +199,9 @@ export function createPresignedUrlPlugin(options) {
                                     const bucket = await withRequestPgClient(vals.withPgClient, vals.pgSettings, (pgClient) => resolveUploadBucket(pgClient, storageConfig, databaseId, vals.bucketKey ?? null, vals.ownerId ?? null, vals.isPublic === true));
                                     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;
+                                    // The reconciler records the coordinate; consumers never
+                                    // recompute it from the logical bucket row.
+                                    const physicalName = assertBucketReconciled(bucket, databaseId);
                                     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, {
@@ -306,11 +304,9 @@ export function createPresignedUrlPlugin(options) {
                                     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;
+                                    // The reconciler records the coordinate; consumers never
+                                    // recompute it from the logical bucket row.
+                                    const physicalName = assertBucketReconciled(bucket, databaseId);
                                     const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
                                     // File row INSERTs under the request role (RLS enforced).
                                     return withRequestPgClient(vals.withPgClient, vals.pgSettings, async (txClient) => {

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

@@ -91,14 +91,6 @@ export declare function getBucketConfig(pgClient: {
         rows: unknown[];
     }>;
 }, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: string, ownerId?: string): Promise<BucketConfig | null>;
-/**
- * Check whether an S3 bucket has already been provisioned (cached).
- */
-export declare function isS3BucketProvisioned(s3BucketName: string): boolean;
-/**
- * Mark an S3 bucket as provisioned in the in-memory cache.
- */
-export declare function markS3BucketProvisioned(s3BucketName: string): void;
 /**
  * Clear the storage module cache AND bucket cache.
  * Useful for testing or schema changes.

package/esm/storage-module-cache.js

@@ -260,34 +260,6 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.scope})`);
     return config;
 }
-// --- S3 bucket existence cache ---
-/**
- * In-memory set of S3 bucket names that are known to exist.
- *
- * Used by the lazy provisioning logic in the presigned URL plugin:
- * before generating a presigned PUT URL, the plugin checks this set.
- * If the bucket name is absent, it calls `ensureBucketProvisioned`
- * to create the S3 bucket, then adds the name here. Subsequent
- * requests for the same bucket skip the provisioning entirely.
- *
- * No TTL needed — S3 buckets are never deleted during normal operation.
- * The set resets on server restart, which is fine because the
- * provisioner's createBucket is idempotent (handles "already exists").
- */
-const provisionedBuckets = new Set();
-/**
- * Check whether an S3 bucket has already been provisioned (cached).
- */
-export function isS3BucketProvisioned(s3BucketName) {
-    return provisionedBuckets.has(s3BucketName);
-}
-/**
- * Mark an S3 bucket as provisioned in the in-memory cache.
- */
-export function markS3BucketProvisioned(s3BucketName) {
-    provisionedBuckets.add(s3BucketName);
-    log.debug(`Marked S3 bucket "${s3BucketName}" as provisioned`);
-}
 /**
  * Clear the storage module cache AND bucket cache.
  * Useful for testing or schema changes.
@@ -295,7 +267,6 @@ export function markS3BucketProvisioned(s3BucketName) {
 export function clearStorageModuleCache() {
     storageModuleCache.clear();
     bucketCache.clear();
-    provisionedBuckets.clear();
 }
 /**
  * Clear cached bucket entries for a specific database.

package/esm/types.d.ts

@@ -12,10 +12,9 @@ export interface BucketConfig {
     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.
+     * The physical S3/MinIO bucket name recorded by reconciliation. NULL until
+     * reconciliation completes. Once set, it is the source of truth for the
+     * physical bucket — reads never reconstruct the name.
      */
     physical_name: string | null;
 }
@@ -178,51 +177,10 @@ export interface S3Config {
  * env-var reads and S3Client creation at module import time.
  */
 export type S3ConfigOrGetter = S3Config | (() => S3Config);
-/**
- * Function to derive the actual S3 bucket name for a given database and bucket key.
- *
- * When provided, the presigned URL plugin calls this on every request
- * to determine which S3 bucket to use — enabling per-(database, bucketKey)
- * isolation. If not provided, falls back to `s3Config.bucket` (global).
- *
- * @param databaseId - The metaschema database UUID
- * @param bucketKey - The logical bucket key (e.g., "public", "private")
- * @returns The S3 bucket name for this database + bucket key
- */
-export type BucketNameResolver = (databaseId: string, bucketKey: string) => string;
-/**
- * Callback to lazily provision an S3 bucket on first use.
- *
- * Called by the presigned URL plugin before generating a presigned PUT URL
- * when the bucket has not been seen before (tracked in an in-memory cache).
- * The implementation should create and fully configure the S3 bucket
- * (privacy policies, CORS, lifecycle rules, etc.) — or no-op if the
- * bucket already exists.
- *
- * @param bucketName - The S3 bucket name to provision
- * @param accessType - The logical bucket type ('public', 'private', 'temp')
- * @param databaseId - The metaschema database UUID
- * @param allowedOrigins - Per-database CORS origins (from storage_module), or null to use global fallback
- */
-export type EnsureBucketProvisioned = (bucketName: string, accessType: 'public' | 'private' | 'temp', databaseId: string, allowedOrigins: string[] | null) => Promise<void>;
 /**
  * Plugin options for the presigned URL plugin.
  */
 export interface PresignedUrlPluginOptions {
     /** S3 configuration (concrete or lazy getter) */
     s3: S3ConfigOrGetter;
-    /**
-     * Optional function to resolve S3 bucket name per-database.
-     * When set, each database gets its own S3 bucket instead of sharing
-     * the global `s3Config.bucket`. The S3 credentials (client) remain shared.
-     */
-    resolveBucketName?: BucketNameResolver;
-    /**
-     * Optional callback to lazily provision an S3 bucket on first upload.
-     * When set, the plugin calls this before generating a presigned PUT URL
-     * for any S3 bucket it hasn't seen yet (tracked in an in-memory cache).
-     * This enables graceful bucket creation without requiring buckets to
-     * exist at database provisioning time.
-     */
-    ensureBucketProvisioned?: EnsureBucketProvisioned;
 }

package/index.d.ts

@@ -34,11 +34,11 @@ export { createDownloadUrlPlugin } from './download-url-field';
 export type { FileRefFieldBinding } from './file-ref-registry';
 export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
 export { assertUploadAllowedByBucket, buildFileProjection, type FileProjection, finalizeStagedUpload, type ManagedUploadTarget, resolveManagedUploadTarget, } from './managed-upload';
-export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, resolveS3ForDatabase } from './physical-bucket';
+export { assertBucketReconciled, resolveS3, resolveS3ForDatabase, StorageBucketNotReconciledError, } from './physical-bucket';
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { type WithPgClient, withRequestPgClient } from './request-pg-client';
 export { describeS3Failure, s3FailureError } from './s3-failure';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
-export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
-export type { BucketConfig, BucketNameResolver, EnsureBucketProvisioned, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';
+export { clearBucketCache, clearStorageModuleCache, getBucketConfig, loadAllStorageModules, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
+export type { BucketConfig, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';

package/index.js

@@ -28,7 +28,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.s3FailureError = exports.describeS3Failure = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.resolveS3ForDatabase = exports.resolveS3 = exports.provisionAndRecordPhysicalBucket = exports.mintPhysicalBucketName = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.validateCustomKey = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
+exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.loadAllStorageModules = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.s3FailureError = exports.describeS3Failure = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.StorageBucketNotReconciledError = exports.resolveS3ForDatabase = exports.resolveS3 = exports.assertBucketReconciled = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.validateCustomKey = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
 var confirm_upload_1 = require("./confirm-upload");
 Object.defineProperty(exports, "CONFIRM_PREFIX_BYTES", { enumerable: true, get: function () { return confirm_upload_1.CONFIRM_PREFIX_BYTES; } });
 Object.defineProperty(exports, "confirmUploadedBytes", { enumerable: true, get: function () { return confirm_upload_1.confirmUploadedBytes; } });
@@ -48,10 +48,10 @@ Object.defineProperty(exports, "buildFileProjection", { enumerable: true, get: f
 Object.defineProperty(exports, "finalizeStagedUpload", { enumerable: true, get: function () { return managed_upload_1.finalizeStagedUpload; } });
 Object.defineProperty(exports, "resolveManagedUploadTarget", { enumerable: true, get: function () { return managed_upload_1.resolveManagedUploadTarget; } });
 var physical_bucket_1 = require("./physical-bucket");
-Object.defineProperty(exports, "mintPhysicalBucketName", { enumerable: true, get: function () { return physical_bucket_1.mintPhysicalBucketName; } });
-Object.defineProperty(exports, "provisionAndRecordPhysicalBucket", { enumerable: true, get: function () { return physical_bucket_1.provisionAndRecordPhysicalBucket; } });
+Object.defineProperty(exports, "assertBucketReconciled", { enumerable: true, get: function () { return physical_bucket_1.assertBucketReconciled; } });
 Object.defineProperty(exports, "resolveS3", { enumerable: true, get: function () { return physical_bucket_1.resolveS3; } });
 Object.defineProperty(exports, "resolveS3ForDatabase", { enumerable: true, get: function () { return physical_bucket_1.resolveS3ForDatabase; } });
+Object.defineProperty(exports, "StorageBucketNotReconciledError", { enumerable: true, get: function () { return physical_bucket_1.StorageBucketNotReconciledError; } });
 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; } });
@@ -73,8 +73,6 @@ 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, "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; } });
 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/managed-upload.js

@@ -140,9 +140,7 @@ async function resolveManagedUploadTarget(args) {
             'the multipart upload lane only writes content-addressed keys. Use the presigned upload ' +
             'mutation with an explicit key.');
     }
-    const physicalName = bucket.physical_name === null
-        ? await (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-        : bucket.physical_name;
+    const physicalName = (0, physical_bucket_1.assertBucketReconciled)(bucket, databaseId);
     return {
         databaseId,
         storageConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.17.0",
+  "version": "1.18.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",
@@ -62,5 +62,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "b91ecc6db944b29a29b5474268de54ddca5dc34a"
+  "gitHead": "77d58bb93796be91d4e00156bb6847392584d3bc"
 }

package/physical-bucket.d.ts

@@ -1,15 +1,21 @@
 /**
- * Physical bucket coordinates: minting a name once, recording it, and building
- * an S3 config against a *known* name.
+ * Physical bucket coordinates: reading the reconciler's recorded name and
+ * building an S3 config against that known name.
  *
  * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
- * mapping is recorded on the bucket row the first time it is provisioned, and
- * from then on the recorded value is the only coordinate anything reads — no
- * name is ever recomputed from a prefix convention, and there is no
- * environment-level bucket standing in for a tenant's.
+ * mapping is recorded on the bucket row by the storage reconciler, and that
+ * value is the only coordinate anything reads — no name is ever recomputed.
  */
-import { type WithPgClient } from './request-pg-client';
 import type { BucketConfig, PresignedUrlPluginOptions, S3Config, StorageModuleConfig } from './types';
+export declare class StorageBucketNotReconciledError extends Error {
+    readonly code = "STORAGE_BUCKET_NOT_RECONCILED";
+    readonly retryable = true;
+    readonly extensions: {
+        code: string;
+        retryable: boolean;
+    };
+    constructor(bucket: BucketConfig, databaseId: string);
+}
 /**
  * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
  * a lazy getter on first use.
@@ -19,42 +25,14 @@ import type { BucketConfig, PresignedUrlPluginOptions, S3Config, StorageModuleCo
  * resolves its physical bucket from the tenant's bucket row.
  */
 export declare function resolveS3(options: PresignedUrlPluginOptions): S3Config;
-/**
- * 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.
- *
- * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
- * name is not a tenant's storage, and silently minting one is how objects ended
- * up in a bucket no database owned. A deployment that wants per-tenant buckets
- * must supply the policy.
- */
-export declare function mintPhysicalBucketName(options: PresignedUrlPluginOptions, databaseId: string, bucketKey: string): string;
 /**
  * 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.
+ * required — callers must resolve the coordinate from the stored row value
+ * before getting here. No name is ever recomputed.
  */
 export declare function resolveS3ForDatabase(options: PresignedUrlPluginOptions, storageConfig: StorageModuleConfig, physicalName: string): S3Config;
 /**
- * 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.
+ * Return the reconciler's recorded physical name, or fail with a typed,
+ * retryable error while reconciliation is still pending.
  */
-export declare function provisionAndRecordPhysicalBucket(options: PresignedUrlPluginOptions, withPgClient: WithPgClient, storageConfig: StorageModuleConfig, databaseId: string, bucket: BucketConfig, allowedOrigins: string[] | null): Promise<string>;
+export declare function assertBucketReconciled(bucket: BucketConfig, databaseId: string): string;

package/physical-bucket.js

@@ -1,25 +1,32 @@
 "use strict";
 /**
- * Physical bucket coordinates: minting a name once, recording it, and building
- * an S3 config against a *known* name.
+ * Physical bucket coordinates: reading the reconciler's recorded name and
+ * building an S3 config against that known name.
  *
  * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
- * mapping is recorded on the bucket row the first time it is provisioned, and
- * from then on the recorded value is the only coordinate anything reads — no
- * name is ever recomputed from a prefix convention, and there is no
- * environment-level bucket standing in for a tenant's.
+ * mapping is recorded on the bucket row by the storage reconciler, and that
+ * value is the only coordinate anything reads — no name is ever recomputed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageBucketNotReconciledError = void 0;
 exports.resolveS3 = resolveS3;
-exports.mintPhysicalBucketName = mintPhysicalBucketName;
 exports.resolveS3ForDatabase = resolveS3ForDatabase;
-exports.provisionAndRecordPhysicalBucket = provisionAndRecordPhysicalBucket;
-const logger_1 = require("@pgpmjs/logger");
-const graphile_storage_registry_1 = require("graphile-storage-registry");
-const request_pg_client_1 = require("./request-pg-client");
-const s3_failure_1 = require("./s3-failure");
-const storage_module_cache_1 = require("./storage-module-cache");
-const log = new logger_1.Logger('graphile-presigned-url:physical-bucket');
+exports.assertBucketReconciled = assertBucketReconciled;
+class StorageBucketNotReconciledError extends Error {
+    code = 'STORAGE_BUCKET_NOT_RECONCILED';
+    retryable = true;
+    extensions = {
+        code: 'STORAGE_BUCKET_NOT_RECONCILED',
+        retryable: true,
+    };
+    constructor(bucket, databaseId) {
+        super(`STORAGE_BUCKET_NOT_RECONCILED: bucket "${bucket.key}" (id=${bucket.id}) ` +
+            `for database ${databaseId} has not yet been reconciled; the reconciler has ` +
+            'not yet recorded a physical name');
+        this.name = 'StorageBucketNotReconciledError';
+    }
+}
+exports.StorageBucketNotReconciledError = StorageBucketNotReconciledError;
 /**
  * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
  * a lazy getter on first use.
@@ -36,31 +43,10 @@ function resolveS3(options) {
     }
     return options.s3;
 }
-/**
- * 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.
- *
- * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
- * name is not a tenant's storage, and silently minting one is how objects ended
- * up in a bucket no database owned. A deployment that wants per-tenant buckets
- * must supply the policy.
- */
-function mintPhysicalBucketName(options, databaseId, bucketKey) {
-    if (!options.resolveBucketName) {
-        throw new Error('STORAGE_BUCKET_NAME_POLICY_MISSING: no resolveBucketName was configured, so there is ' +
-            `no name to provision for bucket "${bucketKey}" of database ${databaseId}. ` +
-            'Physical bucket naming is a deployment policy; the configured s3.bucket is a ' +
-            'connection default and is never a tenant bucket.');
-    }
-    return options.resolveBucketName(databaseId, bucketKey);
-}
 /**
  * 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.
+ * required — callers must resolve the coordinate from the stored row value
+ * before getting here. No name is ever recomputed.
  */
 function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
@@ -77,46 +63,11 @@ function resolveS3ForDatabase(options, storageConfig, physicalName) {
     };
 }
 /**
- * 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.
+ * Return the reconciler's recorded physical name, or fail with a typed,
+ * retryable error while reconciliation is still pending.
  */
-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}`);
-        try {
-            await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
-        }
-        catch (err) {
-            // The first upload to a bucket is where an unreachable object store is
-            // discovered, and the transport's own message is routinely empty: name the
-            // endpoint it could not reach so the response says what is misconfigured.
-            throw (0, s3_failure_1.s3FailureError)('BUCKET_PROVISION_FAILED', { endpoint: resolveS3(options).endpoint, bucket: s3BucketName, databaseId }, err);
-        }
-        (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) => (0, graphile_storage_registry_1.recordPhysicalName)((query) => client.query(query), storageConfig.bucketsQualifiedName, bucket.id, s3BucketName));
-    bucket.physical_name = s3BucketName;
-    log.info(`Recorded physical_name="${s3BucketName}" on bucket ${bucket.id}`);
-    return s3BucketName;
+function assertBucketReconciled(bucket, databaseId) {
+    if (bucket.physical_name !== null)
+        return bucket.physical_name;
+    throw new StorageBucketNotReconciledError(bucket, databaseId);
 }

package/plugin.js

@@ -203,11 +203,9 @@ function createPresignedUrlPlugin(options) {
                                     const bucket = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => resolveUploadBucket(pgClient, storageConfig, databaseId, vals.bucketKey ?? null, vals.ownerId ?? null, vals.isPublic === true));
                                     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 (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-                                        : bucket.physical_name;
+                                    // The reconciler records the coordinate; consumers never
+                                    // recompute it from the logical bucket row.
+                                    const physicalName = (0, physical_bucket_1.assertBucketReconciled)(bucket, databaseId);
                                     const s3ForDb = (0, physical_bucket_1.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, {
@@ -310,11 +308,9 @@ function createPresignedUrlPlugin(options) {
                                     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 (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-                                        : bucket.physical_name;
+                                    // The reconciler records the coordinate; consumers never
+                                    // recompute it from the logical bucket row.
+                                    const physicalName = (0, physical_bucket_1.assertBucketReconciled)(bucket, databaseId);
                                     const s3ForDb = (0, physical_bucket_1.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) => {

package/storage-module-cache.d.ts

@@ -91,14 +91,6 @@ export declare function getBucketConfig(pgClient: {
         rows: unknown[];
     }>;
 }, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: string, ownerId?: string): Promise<BucketConfig | null>;
-/**
- * Check whether an S3 bucket has already been provisioned (cached).
- */
-export declare function isS3BucketProvisioned(s3BucketName: string): boolean;
-/**
- * Mark an S3 bucket as provisioned in the in-memory cache.
- */
-export declare function markS3BucketProvisioned(s3BucketName: string): void;
 /**
  * Clear the storage module cache AND bucket cache.
  * Useful for testing or schema changes.

package/storage-module-cache.js

@@ -5,8 +5,6 @@ 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");
@@ -271,34 +269,6 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.scope})`);
     return config;
 }
-// --- S3 bucket existence cache ---
-/**
- * In-memory set of S3 bucket names that are known to exist.
- *
- * Used by the lazy provisioning logic in the presigned URL plugin:
- * before generating a presigned PUT URL, the plugin checks this set.
- * If the bucket name is absent, it calls `ensureBucketProvisioned`
- * to create the S3 bucket, then adds the name here. Subsequent
- * requests for the same bucket skip the provisioning entirely.
- *
- * No TTL needed — S3 buckets are never deleted during normal operation.
- * The set resets on server restart, which is fine because the
- * provisioner's createBucket is idempotent (handles "already exists").
- */
-const provisionedBuckets = new Set();
-/**
- * Check whether an S3 bucket has already been provisioned (cached).
- */
-function isS3BucketProvisioned(s3BucketName) {
-    return provisionedBuckets.has(s3BucketName);
-}
-/**
- * Mark an S3 bucket as provisioned in the in-memory cache.
- */
-function markS3BucketProvisioned(s3BucketName) {
-    provisionedBuckets.add(s3BucketName);
-    log.debug(`Marked S3 bucket "${s3BucketName}" as provisioned`);
-}
 /**
  * Clear the storage module cache AND bucket cache.
  * Useful for testing or schema changes.
@@ -306,7 +276,6 @@ function markS3BucketProvisioned(s3BucketName) {
 function clearStorageModuleCache() {
     storageModuleCache.clear();
     bucketCache.clear();
-    provisionedBuckets.clear();
 }
 /**
  * Clear cached bucket entries for a specific database.

package/types.d.ts

@@ -12,10 +12,9 @@ export interface BucketConfig {
     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.
+     * The physical S3/MinIO bucket name recorded by reconciliation. NULL until
+     * reconciliation completes. Once set, it is the source of truth for the
+     * physical bucket — reads never reconstruct the name.
      */
     physical_name: string | null;
 }
@@ -178,51 +177,10 @@ export interface S3Config {
  * env-var reads and S3Client creation at module import time.
  */
 export type S3ConfigOrGetter = S3Config | (() => S3Config);
-/**
- * Function to derive the actual S3 bucket name for a given database and bucket key.
- *
- * When provided, the presigned URL plugin calls this on every request
- * to determine which S3 bucket to use — enabling per-(database, bucketKey)
- * isolation. If not provided, falls back to `s3Config.bucket` (global).
- *
- * @param databaseId - The metaschema database UUID
- * @param bucketKey - The logical bucket key (e.g., "public", "private")
- * @returns The S3 bucket name for this database + bucket key
- */
-export type BucketNameResolver = (databaseId: string, bucketKey: string) => string;
-/**
- * Callback to lazily provision an S3 bucket on first use.
- *
- * Called by the presigned URL plugin before generating a presigned PUT URL
- * when the bucket has not been seen before (tracked in an in-memory cache).
- * The implementation should create and fully configure the S3 bucket
- * (privacy policies, CORS, lifecycle rules, etc.) — or no-op if the
- * bucket already exists.
- *
- * @param bucketName - The S3 bucket name to provision
- * @param accessType - The logical bucket type ('public', 'private', 'temp')
- * @param databaseId - The metaschema database UUID
- * @param allowedOrigins - Per-database CORS origins (from storage_module), or null to use global fallback
- */
-export type EnsureBucketProvisioned = (bucketName: string, accessType: 'public' | 'private' | 'temp', databaseId: string, allowedOrigins: string[] | null) => Promise<void>;
 /**
  * Plugin options for the presigned URL plugin.
  */
 export interface PresignedUrlPluginOptions {
     /** S3 configuration (concrete or lazy getter) */
     s3: S3ConfigOrGetter;
-    /**
-     * Optional function to resolve S3 bucket name per-database.
-     * When set, each database gets its own S3 bucket instead of sharing
-     * the global `s3Config.bucket`. The S3 credentials (client) remain shared.
-     */
-    resolveBucketName?: BucketNameResolver;
-    /**
-     * Optional callback to lazily provision an S3 bucket on first upload.
-     * When set, the plugin calls this before generating a presigned PUT URL
-     * for any S3 bucket it hasn't seen yet (tracked in an in-memory cache).
-     * This enables graceful bucket creation without requiring buckets to
-     * exist at database provisioning time.
-     */
-    ensureBucketProvisioned?: EnsureBucketProvisioned;
 }