graphile-presigned-url-plugin 0.2.0 → 0.4.0

package/README.md

@@ -1,5 +1,17 @@
 # graphile-presigned-url-plugin
 
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/graphile-presigned-url-plugin"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-presigned-url-plugin%2Fpackage.json"/></a>
+</p>
+
 Presigned URL upload plugin for PostGraphile v5.
 
 ## Features

package/download-url-field.d.ts

@@ -14,14 +14,5 @@
  */
 import type { GraphileConfig } from 'graphile-config';
 import type { PresignedUrlPluginOptions } from './types';
-/**
- * Creates the downloadUrl computed field plugin.
- *
- * This is a separate plugin from the main presigned URL plugin because it
- * uses the GraphQLObjectType_fields hook (low-level) rather than extendSchema.
- * The downloadUrl field needs to be added dynamically to whatever table is
- * the storage module's files table, which we discover at schema-build time
- * via the `@storageFiles` smart tag.
- */
 export declare function createDownloadUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
 export default createDownloadUrlPlugin;

package/download-url-field.js

@@ -28,8 +28,38 @@ const log = new logger_1.Logger('graphile-presigned-url:download-url');
  * the storage module's files table, which we discover at schema-build time
  * via the `@storageFiles` smart tag.
  */
+/**
+ * Resolve the S3 config from the options. If the option is a lazy getter
+ * function, call it (and cache the result).
+ */
+function resolveS3(options) {
+    if (typeof options.s3 === 'function') {
+        const resolved = options.s3();
+        options.s3 = resolved;
+        return resolved;
+    }
+    return options.s3;
+}
+/**
+ * Build a per-database S3Config by overlaying storage_module overrides
+ * onto the global S3Config. Same logic as plugin.ts resolveS3ForDatabase.
+ */
+function resolveS3ForDatabase(options, storageConfig, databaseId) {
+    const globalS3 = resolveS3(options);
+    const bucket = options.resolveBucketName
+        ? options.resolveBucketName(databaseId)
+        : globalS3.bucket;
+    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
+    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+        return globalS3;
+    }
+    return {
+        ...globalS3,
+        bucket,
+        ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
+    };
+}
 function createDownloadUrlPlugin(options) {
-    const { s3 } = options;
     return {
         name: 'PresignedUrlDownloadPlugin',
         version: '0.1.0',
@@ -65,34 +95,39 @@ function createDownloadUrlPlugin(options) {
                                 if (status !== 'ready' && status !== 'processed') {
                                     return null;
                                 }
-                                if (isPublic && s3.publicUrlPrefix) {
-                                    // Public file: return direct URL
-                                    return `${s3.publicUrlPrefix}/${key}`;
-                                }
-                                // Resolve download URL expiry from storage module config (per-database)
+                                // Resolve per-database config (bucket, publicUrlPrefix, expiry)
+                                let s3ForDb = resolveS3(options); // fallback to global
                                 let downloadUrlExpirySeconds = 3600; // fallback default
                                 try {
                                     const withPgClient = context.pgSettings
                                         ? context.withPgClient
                                         : null;
                                     if (withPgClient) {
-                                        const config = await withPgClient(null, async (pgClient) => {
+                                        const resolved = await withPgClient(null, async (pgClient) => {
                                             const dbResult = await pgClient.query(`SELECT jwt_private.current_database_id() AS id`);
                                             const databaseId = dbResult.rows[0]?.id;
                                             if (!databaseId)
                                                 return null;
-                                            return (0, storage_module_cache_1.getStorageModuleConfig)(pgClient, databaseId);
+                                            const config = await (0, storage_module_cache_1.getStorageModuleConfig)(pgClient, databaseId);
+                                            if (!config)
+                                                return null;
+                                            return { config, databaseId };
                                         });
-                                        if (config) {
-                                            downloadUrlExpirySeconds = config.downloadUrlExpirySeconds;
+                                        if (resolved) {
+                                            downloadUrlExpirySeconds = resolved.config.downloadUrlExpirySeconds;
+                                            s3ForDb = resolveS3ForDatabase(options, resolved.config, resolved.databaseId);
                                         }
                                     }
                                 }
                                 catch {
-                                    // Fall back to default if config lookup fails
+                                    // Fall back to global config if lookup fails
+                                }
+                                if (isPublic && s3ForDb.publicUrlPrefix) {
+                                    // Public file: return direct CDN URL (per-database prefix)
+                                    return `${s3ForDb.publicUrlPrefix}/${key}`;
                                 }
-                                // Private file: generate presigned GET URL
-                                return (0, s3_signer_1.generatePresignedGetUrl)(s3, key, downloadUrlExpirySeconds, filename || undefined);
+                                // Private file: generate presigned GET URL (per-database bucket)
+                                return (0, s3_signer_1.generatePresignedGetUrl)(s3ForDb, key, downloadUrlExpirySeconds, filename || undefined);
                             },
                         }),
                     }, 'PresignedUrlDownloadPlugin adding downloadUrl field');

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

@@ -14,14 +14,5 @@
  */
 import type { GraphileConfig } from 'graphile-config';
 import type { PresignedUrlPluginOptions } from './types';
-/**
- * Creates the downloadUrl computed field plugin.
- *
- * This is a separate plugin from the main presigned URL plugin because it
- * uses the GraphQLObjectType_fields hook (low-level) rather than extendSchema.
- * The downloadUrl field needs to be added dynamically to whatever table is
- * the storage module's files table, which we discover at schema-build time
- * via the `@storageFiles` smart tag.
- */
 export declare function createDownloadUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
 export default createDownloadUrlPlugin;

package/esm/download-url-field.js

@@ -25,8 +25,38 @@ const log = new Logger('graphile-presigned-url:download-url');
  * the storage module's files table, which we discover at schema-build time
  * via the `@storageFiles` smart tag.
  */
+/**
+ * Resolve the S3 config from the options. If the option is a lazy getter
+ * function, call it (and cache the result).
+ */
+function resolveS3(options) {
+    if (typeof options.s3 === 'function') {
+        const resolved = options.s3();
+        options.s3 = resolved;
+        return resolved;
+    }
+    return options.s3;
+}
+/**
+ * Build a per-database S3Config by overlaying storage_module overrides
+ * onto the global S3Config. Same logic as plugin.ts resolveS3ForDatabase.
+ */
+function resolveS3ForDatabase(options, storageConfig, databaseId) {
+    const globalS3 = resolveS3(options);
+    const bucket = options.resolveBucketName
+        ? options.resolveBucketName(databaseId)
+        : globalS3.bucket;
+    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
+    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+        return globalS3;
+    }
+    return {
+        ...globalS3,
+        bucket,
+        ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
+    };
+}
 export function createDownloadUrlPlugin(options) {
-    const { s3 } = options;
     return {
         name: 'PresignedUrlDownloadPlugin',
         version: '0.1.0',
@@ -62,34 +92,39 @@ export function createDownloadUrlPlugin(options) {
                                 if (status !== 'ready' && status !== 'processed') {
                                     return null;
                                 }
-                                if (isPublic && s3.publicUrlPrefix) {
-                                    // Public file: return direct URL
-                                    return `${s3.publicUrlPrefix}/${key}`;
-                                }
-                                // Resolve download URL expiry from storage module config (per-database)
+                                // Resolve per-database config (bucket, publicUrlPrefix, expiry)
+                                let s3ForDb = resolveS3(options); // fallback to global
                                 let downloadUrlExpirySeconds = 3600; // fallback default
                                 try {
                                     const withPgClient = context.pgSettings
                                         ? context.withPgClient
                                         : null;
                                     if (withPgClient) {
-                                        const config = await withPgClient(null, async (pgClient) => {
+                                        const resolved = await withPgClient(null, async (pgClient) => {
                                             const dbResult = await pgClient.query(`SELECT jwt_private.current_database_id() AS id`);
                                             const databaseId = dbResult.rows[0]?.id;
                                             if (!databaseId)
                                                 return null;
-                                            return getStorageModuleConfig(pgClient, databaseId);
+                                            const config = await getStorageModuleConfig(pgClient, databaseId);
+                                            if (!config)
+                                                return null;
+                                            return { config, databaseId };
                                         });
-                                        if (config) {
-                                            downloadUrlExpirySeconds = config.downloadUrlExpirySeconds;
+                                        if (resolved) {
+                                            downloadUrlExpirySeconds = resolved.config.downloadUrlExpirySeconds;
+                                            s3ForDb = resolveS3ForDatabase(options, resolved.config, resolved.databaseId);
                                         }
                                     }
                                 }
                                 catch {
-                                    // Fall back to default if config lookup fails
+                                    // Fall back to global config if lookup fails
+                                }
+                                if (isPublic && s3ForDb.publicUrlPrefix) {
+                                    // Public file: return direct CDN URL (per-database prefix)
+                                    return `${s3ForDb.publicUrlPrefix}/${key}`;
                                 }
-                                // Private file: generate presigned GET URL
-                                return generatePresignedGetUrl(s3, key, downloadUrlExpirySeconds, filename || undefined);
+                                // Private file: generate presigned GET URL (per-database bucket)
+                                return generatePresignedGetUrl(s3ForDb, key, downloadUrlExpirySeconds, filename || undefined);
                             },
                         }),
                     }, 'PresignedUrlDownloadPlugin adding downloadUrl field');

package/esm/index.d.ts

@@ -29,6 +29,6 @@
 export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { PresignedUrlPreset } from './preset';
-export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache } from './storage-module-cache';
+export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';
-export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, PresignedUrlPluginOptions, } from './types';
+export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, S3ConfigOrGetter, PresignedUrlPluginOptions, BucketNameResolver, EnsureBucketProvisioned, } from './types';

package/esm/index.js

@@ -29,5 +29,5 @@
 export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { PresignedUrlPreset } from './preset';
-export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache } from './storage-module-cache';
+export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';

package/esm/plugin.js

@@ -19,7 +19,7 @@
 import { context as grafastContext, lambda, object } from 'grafast';
 import { extendSchema, gql } from 'graphile-utils';
 import { Logger } from '@pgpmjs/logger';
-import { getStorageModuleConfig, getBucketConfig } from './storage-module-cache';
+import { getStorageModuleConfig, getBucketConfig, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 import { generatePresignedPutUrl, headObject } from './s3-signer';
 const log = new Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
@@ -52,8 +52,64 @@ async function resolveDatabaseId(pgClient) {
     return result.rows[0]?.id ?? null;
 }
 // --- Plugin factory ---
+/**
+ * Resolve the S3 config from the options. If the option is a lazy getter
+ * function, call it (and cache the result). This avoids reading env vars
+ * or constructing an S3Client at module-import time.
+ */
+function resolveS3(options) {
+    if (typeof options.s3 === 'function') {
+        const resolved = options.s3();
+        // Cache so subsequent calls don't re-evaluate
+        options.s3 = resolved;
+        return resolved;
+    }
+    return options.s3;
+}
+/**
+ * Build a per-database S3Config by overlaying storage_module overrides
+ * onto the global S3Config.
+ *
+ * - Bucket name: from resolveBucketName(databaseId) if provided, else global
+ * - publicUrlPrefix: from storageConfig.publicUrlPrefix if set, else global
+ * - S3 client (credentials, endpoint): always global (shared IAM key)
+ */
+function resolveS3ForDatabase(options, storageConfig, databaseId) {
+    const globalS3 = resolveS3(options);
+    const bucket = options.resolveBucketName
+        ? options.resolveBucketName(databaseId)
+        : globalS3.bucket;
+    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
+    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+        return globalS3;
+    }
+    return {
+        ...globalS3,
+        bucket,
+        ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
+    };
+}
+/**
+ * Ensure the S3 bucket for a database exists, provisioning it lazily if needed.
+ *
+ * Checks an in-memory Set of known-provisioned bucket names. On the first
+ * request for an unseen bucket, calls the `ensureBucketProvisioned` callback
+ * (which creates the bucket with correct CORS, policies, etc.), then marks
+ * it as provisioned so subsequent requests skip the check entirely.
+ *
+ * If no `ensureBucketProvisioned` callback is configured, this is a no-op.
+ */
+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`);
+}
 export function createPresignedUrlPlugin(options) {
-    const { s3 } = options;
     return extendSchema(() => ({
         typeDefs: gql `
       input RequestUploadUrlInput {
@@ -228,8 +284,11 @@ export function createPresignedUrlPlugin(options) {
                                     bucket.is_public,
                                 ]);
                                 const fileId = fileResult.rows[0].id;
-                                // --- Generate presigned PUT URL ---
-                                const uploadUrl = await generatePresignedPutUrl(s3, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
+                                // --- Ensure the S3 bucket exists (lazy provisioning) ---
+                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+                                await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
+                                // --- Generate presigned PUT URL (per-database bucket) ---
+                                const uploadUrl = await generatePresignedPutUrl(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
                                 const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
                                 // --- Track the upload request ---
                                 await pgClient.query(`INSERT INTO ${storageConfig.uploadRequestsQualifiedName}
@@ -295,8 +354,9 @@ export function createPresignedUrlPlugin(options) {
                                         success: true,
                                     };
                                 }
-                                // --- Verify file exists in S3 ---
-                                const s3Head = await headObject(s3, file.key, file.content_type);
+                                // --- Verify file exists in S3 (per-database bucket) ---
+                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+                                const s3Head = await headObject(s3ForDb, file.key, file.content_type);
                                 if (!s3Head) {
                                     throw new Error('FILE_NOT_IN_S3: the file has not been uploaded yet');
                                 }

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

@@ -28,6 +28,14 @@ export declare function getBucketConfig(pgClient: {
         rows: unknown[];
     }>;
 }, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: 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

@@ -38,6 +38,10 @@ const STORAGE_MODULE_QUERY = `
     ft.name AS files_table,
     urs.schema_name AS upload_requests_schema,
     urt.name AS upload_requests_table,
+    sm.endpoint,
+    sm.public_url_prefix,
+    sm.provider,
+    sm.allowed_origins,
     sm.upload_url_expiry_seconds,
     sm.download_url_expiry_seconds,
     sm.default_max_file_size,
@@ -83,6 +87,10 @@ export async function getStorageModuleConfig(pgClient, databaseId) {
         bucketsTableName: row.buckets_table,
         filesTableName: row.files_table,
         uploadRequestsTableName: row.upload_requests_table,
+        endpoint: row.endpoint,
+        publicUrlPrefix: row.public_url_prefix,
+        provider: row.provider,
+        allowedOrigins: row.allowed_origins,
         uploadUrlExpirySeconds: row.upload_url_expiry_seconds ?? DEFAULT_UPLOAD_URL_EXPIRY_SECONDS,
         downloadUrlExpirySeconds: row.download_url_expiry_seconds ?? DEFAULT_DOWNLOAD_URL_EXPIRY_SECONDS,
         defaultMaxFileSize: row.default_max_file_size ?? DEFAULT_MAX_FILE_SIZE,
@@ -153,6 +161,34 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id})`);
     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.
@@ -160,6 +196,7 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
 export function clearStorageModuleCache() {
     storageModuleCache.clear();
     bucketCache.clear();
+    provisionedBuckets.clear();
 }
 /**
  * Clear cached bucket entries for a specific database.

package/esm/types.d.ts

@@ -31,6 +31,14 @@ export interface StorageModuleConfig {
     filesTableName: string;
     /** Upload requests table name */
     uploadRequestsTableName: string;
+    /** S3-compatible API endpoint URL (per-database override) */
+    endpoint: string | null;
+    /** Public URL prefix for generating download URLs (per-database override) */
+    publicUrlPrefix: string | null;
+    /** Storage provider type: 'minio', 's3', 'gcs', etc. (per-database override) */
+    provider: string | null;
+    /** CORS allowed origins (per-database override, NULL = use global fallback) */
+    allowedOrigins: string[] | null;
     /** Presigned PUT URL expiry in seconds (default: 900 = 15 min) */
     uploadUrlExpirySeconds: number;
     /** Presigned GET URL expiry in seconds (default: 3600 = 1 hour) */
@@ -107,10 +115,57 @@ export interface S3Config {
     /** Public URL prefix for generating download URLs */
     publicUrlPrefix?: string;
 }
+/**
+ * S3 configuration or a lazy getter that returns it on first use.
+ * When a function is provided, it will only be called when the first
+ * mutation or resolver actually needs the S3 client — avoiding eager
+ * 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.
+ *
+ * When provided, the presigned URL plugin calls this on every request
+ * to determine which S3 bucket to use — enabling per-database bucket
+ * isolation. If not provided, falls back to `s3Config.bucket` (global).
+ *
+ * @param databaseId - The metaschema database UUID
+ * @returns The S3 bucket name for this database
+ */
+export type BucketNameResolver = (databaseId: 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 */
-    s3: S3Config;
+    /** 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

@@ -29,6 +29,6 @@
 export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { PresignedUrlPreset } from './preset';
-export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache } from './storage-module-cache';
+export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
 export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';
-export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, PresignedUrlPluginOptions, } from './types';
+export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, S3ConfigOrGetter, PresignedUrlPluginOptions, BucketNameResolver, EnsureBucketProvisioned, } from './types';

package/index.js

@@ -28,7 +28,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.headObject = exports.generatePresignedGetUrl = exports.generatePresignedPutUrl = exports.clearBucketCache = exports.clearStorageModuleCache = exports.getBucketConfig = exports.getStorageModuleConfig = exports.PresignedUrlPreset = exports.createDownloadUrlPlugin = exports.createPresignedUrlPlugin = exports.PresignedUrlPlugin = void 0;
+exports.headObject = exports.generatePresignedGetUrl = exports.generatePresignedPutUrl = exports.markS3BucketProvisioned = exports.isS3BucketProvisioned = exports.clearBucketCache = exports.clearStorageModuleCache = exports.getBucketConfig = exports.getStorageModuleConfig = exports.PresignedUrlPreset = exports.createDownloadUrlPlugin = exports.createPresignedUrlPlugin = exports.PresignedUrlPlugin = void 0;
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "PresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.PresignedUrlPlugin; } });
 Object.defineProperty(exports, "createPresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.createPresignedUrlPlugin; } });
@@ -41,6 +41,8 @@ Object.defineProperty(exports, "getStorageModuleConfig", { enumerable: true, get
 Object.defineProperty(exports, "getBucketConfig", { enumerable: true, get: function () { return storage_module_cache_1.getBucketConfig; } });
 Object.defineProperty(exports, "clearStorageModuleCache", { enumerable: true, get: function () { return storage_module_cache_1.clearStorageModuleCache; } });
 Object.defineProperty(exports, "clearBucketCache", { enumerable: true, get: function () { return storage_module_cache_1.clearBucketCache; } });
+Object.defineProperty(exports, "isS3BucketProvisioned", { enumerable: true, get: function () { return storage_module_cache_1.isS3BucketProvisioned; } });
+Object.defineProperty(exports, "markS3BucketProvisioned", { enumerable: true, get: function () { return storage_module_cache_1.markS3BucketProvisioned; } });
 var s3_signer_1 = require("./s3-signer");
 Object.defineProperty(exports, "generatePresignedPutUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedPutUrl; } });
 Object.defineProperty(exports, "generatePresignedGetUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedGetUrl; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl, confirmUpload mutations and downloadUrl computed field",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -55,8 +55,9 @@
     "postgraphile": "5.0.0"
   },
   "devDependencies": {
+    "@constructive-io/s3-utils": "^2.10.2",
     "@types/node": "^22.19.11",
     "makage": "^0.1.10"
   },
-  "gitHead": "fc23b83307d007a14e54b1d0fc36614b9650a5dc"
+  "gitHead": "3bf7c522cf9f9d2595750ac7cea81d470b3e6c30"
 }

package/plugin.js

@@ -56,8 +56,64 @@ async function resolveDatabaseId(pgClient) {
     return result.rows[0]?.id ?? null;
 }
 // --- Plugin factory ---
+/**
+ * Resolve the S3 config from the options. If the option is a lazy getter
+ * function, call it (and cache the result). This avoids reading env vars
+ * or constructing an S3Client at module-import time.
+ */
+function resolveS3(options) {
+    if (typeof options.s3 === 'function') {
+        const resolved = options.s3();
+        // Cache so subsequent calls don't re-evaluate
+        options.s3 = resolved;
+        return resolved;
+    }
+    return options.s3;
+}
+/**
+ * Build a per-database S3Config by overlaying storage_module overrides
+ * onto the global S3Config.
+ *
+ * - Bucket name: from resolveBucketName(databaseId) if provided, else global
+ * - publicUrlPrefix: from storageConfig.publicUrlPrefix if set, else global
+ * - S3 client (credentials, endpoint): always global (shared IAM key)
+ */
+function resolveS3ForDatabase(options, storageConfig, databaseId) {
+    const globalS3 = resolveS3(options);
+    const bucket = options.resolveBucketName
+        ? options.resolveBucketName(databaseId)
+        : globalS3.bucket;
+    const publicUrlPrefix = storageConfig.publicUrlPrefix ?? globalS3.publicUrlPrefix;
+    if (bucket === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
+        return globalS3;
+    }
+    return {
+        ...globalS3,
+        bucket,
+        ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
+    };
+}
+/**
+ * Ensure the S3 bucket for a database exists, provisioning it lazily if needed.
+ *
+ * Checks an in-memory Set of known-provisioned bucket names. On the first
+ * request for an unseen bucket, calls the `ensureBucketProvisioned` callback
+ * (which creates the bucket with correct CORS, policies, etc.), then marks
+ * it as provisioned so subsequent requests skip the check entirely.
+ *
+ * If no `ensureBucketProvisioned` callback is configured, this is a no-op.
+ */
+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`);
+}
 function createPresignedUrlPlugin(options) {
-    const { s3 } = options;
     return (0, graphile_utils_1.extendSchema)(() => ({
         typeDefs: (0, graphile_utils_1.gql) `
       input RequestUploadUrlInput {
@@ -232,8 +288,11 @@ function createPresignedUrlPlugin(options) {
                                     bucket.is_public,
                                 ]);
                                 const fileId = fileResult.rows[0].id;
-                                // --- Generate presigned PUT URL ---
-                                const uploadUrl = await (0, s3_signer_1.generatePresignedPutUrl)(s3, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
+                                // --- Ensure the S3 bucket exists (lazy provisioning) ---
+                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+                                await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
+                                // --- Generate presigned PUT URL (per-database bucket) ---
+                                const uploadUrl = await (0, s3_signer_1.generatePresignedPutUrl)(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
                                 const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
                                 // --- Track the upload request ---
                                 await pgClient.query(`INSERT INTO ${storageConfig.uploadRequestsQualifiedName}
@@ -299,8 +358,9 @@ function createPresignedUrlPlugin(options) {
                                         success: true,
                                     };
                                 }
-                                // --- Verify file exists in S3 ---
-                                const s3Head = await (0, s3_signer_1.headObject)(s3, file.key, file.content_type);
+                                // --- Verify file exists in S3 (per-database bucket) ---
+                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+                                const s3Head = await (0, s3_signer_1.headObject)(s3ForDb, file.key, file.content_type);
                                 if (!s3Head) {
                                     throw new Error('FILE_NOT_IN_S3: the file has not been uploaded yet');
                                 }

package/storage-module-cache.d.ts

@@ -28,6 +28,14 @@ export declare function getBucketConfig(pgClient: {
         rows: unknown[];
     }>;
 }, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: 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

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getStorageModuleConfig = getStorageModuleConfig;
 exports.getBucketConfig = getBucketConfig;
+exports.isS3BucketProvisioned = isS3BucketProvisioned;
+exports.markS3BucketProvisioned = markS3BucketProvisioned;
 exports.clearStorageModuleCache = clearStorageModuleCache;
 exports.clearBucketCache = clearBucketCache;
 const logger_1 = require("@pgpmjs/logger");
@@ -44,6 +46,10 @@ const STORAGE_MODULE_QUERY = `
     ft.name AS files_table,
     urs.schema_name AS upload_requests_schema,
     urt.name AS upload_requests_table,
+    sm.endpoint,
+    sm.public_url_prefix,
+    sm.provider,
+    sm.allowed_origins,
     sm.upload_url_expiry_seconds,
     sm.download_url_expiry_seconds,
     sm.default_max_file_size,
@@ -89,6 +95,10 @@ async function getStorageModuleConfig(pgClient, databaseId) {
         bucketsTableName: row.buckets_table,
         filesTableName: row.files_table,
         uploadRequestsTableName: row.upload_requests_table,
+        endpoint: row.endpoint,
+        publicUrlPrefix: row.public_url_prefix,
+        provider: row.provider,
+        allowedOrigins: row.allowed_origins,
         uploadUrlExpirySeconds: row.upload_url_expiry_seconds ?? DEFAULT_UPLOAD_URL_EXPIRY_SECONDS,
         downloadUrlExpirySeconds: row.download_url_expiry_seconds ?? DEFAULT_DOWNLOAD_URL_EXPIRY_SECONDS,
         defaultMaxFileSize: row.default_max_file_size ?? DEFAULT_MAX_FILE_SIZE,
@@ -159,6 +169,34 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey) {
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id})`);
     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.
@@ -166,6 +204,7 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey) {
 function clearStorageModuleCache() {
     storageModuleCache.clear();
     bucketCache.clear();
+    provisionedBuckets.clear();
 }
 /**
  * Clear cached bucket entries for a specific database.

package/types.d.ts

@@ -31,6 +31,14 @@ export interface StorageModuleConfig {
     filesTableName: string;
     /** Upload requests table name */
     uploadRequestsTableName: string;
+    /** S3-compatible API endpoint URL (per-database override) */
+    endpoint: string | null;
+    /** Public URL prefix for generating download URLs (per-database override) */
+    publicUrlPrefix: string | null;
+    /** Storage provider type: 'minio', 's3', 'gcs', etc. (per-database override) */
+    provider: string | null;
+    /** CORS allowed origins (per-database override, NULL = use global fallback) */
+    allowedOrigins: string[] | null;
     /** Presigned PUT URL expiry in seconds (default: 900 = 15 min) */
     uploadUrlExpirySeconds: number;
     /** Presigned GET URL expiry in seconds (default: 3600 = 1 hour) */
@@ -107,10 +115,57 @@ export interface S3Config {
     /** Public URL prefix for generating download URLs */
     publicUrlPrefix?: string;
 }
+/**
+ * S3 configuration or a lazy getter that returns it on first use.
+ * When a function is provided, it will only be called when the first
+ * mutation or resolver actually needs the S3 client — avoiding eager
+ * 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.
+ *
+ * When provided, the presigned URL plugin calls this on every request
+ * to determine which S3 bucket to use — enabling per-database bucket
+ * isolation. If not provided, falls back to `s3Config.bucket` (global).
+ *
+ * @param databaseId - The metaschema database UUID
+ * @returns The S3 bucket name for this database
+ */
+export type BucketNameResolver = (databaseId: 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 */
-    s3: S3Config;
+    /** 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;
 }