graphile-presigned-url-plugin 0.2.0

package/plugin.js

@@ -0,0 +1,343 @@
+"use strict";
+/**
+ * Presigned URL Plugin for PostGraphile v5
+ *
+ * Adds presigned URL upload support to PostGraphile v5:
+ *
+ * 1. `requestUploadUrl` mutation — generates a presigned PUT URL for direct
+ *    client-to-S3 upload. Checks bucket access via RLS, deduplicates by
+ *    content hash, tracks the request in upload_requests.
+ *
+ * 2. `confirmUpload` mutation — confirms a file was uploaded to S3, verifies
+ *    the object exists with correct content-type, transitions file status
+ *    from 'pending' to 'ready'.
+ *
+ * 3. `downloadUrl` computed field on File types — generates presigned GET URLs
+ *    for private files, returns public URL prefix + key for public files.
+ *
+ * Uses the extendSchema + grafast plan pattern (same as PublicKeySignature).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PresignedUrlPlugin = void 0;
+exports.createPresignedUrlPlugin = createPresignedUrlPlugin;
+const grafast_1 = require("grafast");
+const graphile_utils_1 = require("graphile-utils");
+const logger_1 = require("@pgpmjs/logger");
+const storage_module_cache_1 = require("./storage-module-cache");
+const s3_signer_1 = require("./s3-signer");
+const log = new logger_1.Logger('graphile-presigned-url:plugin');
+// --- Protocol-level constants (not configurable) ---
+const MAX_CONTENT_HASH_LENGTH = 128;
+const MAX_CONTENT_TYPE_LENGTH = 255;
+const MAX_BUCKET_KEY_LENGTH = 255;
+const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/;
+// --- Helpers ---
+/**
+ * Validate a SHA-256 hex string.
+ */
+function isValidSha256(hash) {
+    return SHA256_HEX_REGEX.test(hash);
+}
+/**
+ * Build the S3 key from content hash and content type extension.
+ * Format: {contentHash} (flat namespace, content-addressed)
+ */
+function buildS3Key(contentHash) {
+    return contentHash;
+}
+/**
+ * Resolve the database_id from the JWT context.
+ * The server middleware sets jwt.claims.database_id, which is accessible
+ * via jwt_private.current_database_id() — a simple function call, no
+ * metaschema query needed.
+ */
+async function resolveDatabaseId(pgClient) {
+    const result = await pgClient.query(`SELECT jwt_private.current_database_id() AS id`);
+    return result.rows[0]?.id ?? null;
+}
+// --- Plugin factory ---
+function createPresignedUrlPlugin(options) {
+    const { s3 } = options;
+    return (0, graphile_utils_1.extendSchema)(() => ({
+        typeDefs: (0, graphile_utils_1.gql) `
+      input RequestUploadUrlInput {
+        """Bucket key (e.g., "public", "private")"""
+        bucketKey: String!
+        """SHA-256 content hash computed by the client (hex-encoded, 64 chars)"""
+        contentHash: String!
+        """MIME type of the file (e.g., "image/png")"""
+        contentType: String!
+        """File size in bytes"""
+        size: Int!
+        """Original filename (optional, for display and Content-Disposition)"""
+        filename: String
+      }
+
+      type RequestUploadUrlPayload {
+        """Presigned PUT URL (null if file was deduplicated)"""
+        uploadUrl: String
+        """The file ID (existing if deduplicated, new if fresh upload)"""
+        fileId: UUID!
+        """The S3 object key"""
+        key: String!
+        """Whether this file was deduplicated (already exists with same hash)"""
+        deduplicated: Boolean!
+        """Presigned URL expiry time (null if deduplicated)"""
+        expiresAt: Datetime
+      }
+
+      input ConfirmUploadInput {
+        """The file ID returned by requestUploadUrl"""
+        fileId: UUID!
+      }
+
+      type ConfirmUploadPayload {
+        """The confirmed file ID"""
+        fileId: UUID!
+        """New file status"""
+        status: String!
+        """Whether confirmation succeeded"""
+        success: Boolean!
+      }
+
+      extend type Mutation {
+        """
+        Request a presigned URL for uploading a file directly to S3.
+        Client computes SHA-256 of the file content and provides it here.
+        If a file with the same hash already exists (dedup), returns the
+        existing file ID and deduplicated=true with no uploadUrl.
+        """
+        requestUploadUrl(
+          input: RequestUploadUrlInput!
+        ): RequestUploadUrlPayload
+
+        """
+        Confirm that a file has been uploaded to S3.
+        Verifies the object exists in S3, checks content-type,
+        and transitions the file status from 'pending' to 'ready'.
+        """
+        confirmUpload(
+          input: ConfirmUploadInput!
+        ): ConfirmUploadPayload
+      }
+    `,
+        plans: {
+            Mutation: {
+                requestUploadUrl(_$mutation, fieldArgs) {
+                    const $input = fieldArgs.getRaw('input');
+                    const $withPgClient = (0, grafast_1.context)().get('withPgClient');
+                    const $pgSettings = (0, grafast_1.context)().get('pgSettings');
+                    const $combined = (0, grafast_1.object)({
+                        input: $input,
+                        withPgClient: $withPgClient,
+                        pgSettings: $pgSettings,
+                    });
+                    return (0, grafast_1.lambda)($combined, async ({ input, withPgClient, pgSettings }) => {
+                        // --- Input validation ---
+                        const { bucketKey, contentHash, contentType, size, filename } = input;
+                        if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
+                            throw new Error('INVALID_BUCKET_KEY');
+                        }
+                        if (!contentHash || typeof contentHash !== 'string' || contentHash.length > MAX_CONTENT_HASH_LENGTH) {
+                            throw new Error('INVALID_CONTENT_HASH');
+                        }
+                        if (!isValidSha256(contentHash)) {
+                            throw new Error('INVALID_CONTENT_HASH_FORMAT: must be a 64-char lowercase hex SHA-256');
+                        }
+                        if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
+                            throw new Error('INVALID_CONTENT_TYPE');
+                        }
+                        return withPgClient(pgSettings, async (pgClient) => {
+                            await pgClient.query('BEGIN');
+                            try {
+                                // --- Resolve storage module config (all limits come from here) ---
+                                const databaseId = await resolveDatabaseId(pgClient);
+                                if (!databaseId) {
+                                    throw new Error('DATABASE_NOT_FOUND');
+                                }
+                                const storageConfig = await (0, storage_module_cache_1.getStorageModuleConfig)(pgClient, databaseId);
+                                if (!storageConfig) {
+                                    throw new Error('STORAGE_MODULE_NOT_PROVISIONED');
+                                }
+                                // --- Validate size against storage module default (bucket override checked below) ---
+                                if (typeof size !== 'number' || size <= 0 || size > storageConfig.defaultMaxFileSize) {
+                                    throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
+                                }
+                                if (filename !== undefined && filename !== null) {
+                                    if (typeof filename !== 'string' || filename.length > storageConfig.maxFilenameLength) {
+                                        throw new Error('INVALID_FILENAME');
+                                    }
+                                }
+                                // --- Look up the bucket (cached; first miss queries via RLS) ---
+                                const bucket = await (0, storage_module_cache_1.getBucketConfig)(pgClient, storageConfig, databaseId, bucketKey);
+                                if (!bucket) {
+                                    throw new Error('BUCKET_NOT_FOUND');
+                                }
+                                // --- Validate content type against bucket's allowed_mime_types ---
+                                if (bucket.allowed_mime_types && bucket.allowed_mime_types.length > 0) {
+                                    const allowed = bucket.allowed_mime_types;
+                                    const isAllowed = allowed.some((pattern) => {
+                                        if (pattern === '*/*')
+                                            return true;
+                                        if (pattern.endsWith('/*')) {
+                                            const prefix = pattern.slice(0, -1);
+                                            return contentType.startsWith(prefix);
+                                        }
+                                        return contentType === pattern;
+                                    });
+                                    if (!isAllowed) {
+                                        throw new Error(`CONTENT_TYPE_NOT_ALLOWED: ${contentType} not in bucket allowed types`);
+                                    }
+                                }
+                                // --- Validate size against bucket's max_file_size ---
+                                if (bucket.max_file_size && size > bucket.max_file_size) {
+                                    throw new Error(`FILE_TOO_LARGE: exceeds bucket max of ${bucket.max_file_size} bytes`);
+                                }
+                                const s3Key = buildS3Key(contentHash);
+                                // --- Dedup check: look for existing file with same content_hash in this bucket ---
+                                const dedupResult = await pgClient.query(`SELECT id, status
+                   FROM ${storageConfig.filesQualifiedName}
+                   WHERE content_hash = $1
+                     AND bucket_id = $2
+                     AND status IN ('ready', 'processed')
+                   LIMIT 1`, [contentHash, bucket.id]);
+                                if (dedupResult.rows.length > 0) {
+                                    const existingFile = dedupResult.rows[0];
+                                    log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
+                                    // Track the dedup request
+                                    await pgClient.query(`INSERT INTO ${storageConfig.uploadRequestsQualifiedName}
+                     (file_id, bucket_id, key, content_type, content_hash, size, status, expires_at)
+                     VALUES ($1, $2, $3, $4, $5, $6, 'confirmed', NOW())`, [existingFile.id, bucket.id, s3Key, contentType, contentHash, size]);
+                                    await pgClient.query('COMMIT');
+                                    return {
+                                        uploadUrl: null,
+                                        fileId: existingFile.id,
+                                        key: s3Key,
+                                        deduplicated: true,
+                                        expiresAt: null,
+                                    };
+                                }
+                                // --- Create file record (status=pending) ---
+                                const fileResult = await pgClient.query(`INSERT INTO ${storageConfig.filesQualifiedName}
+                   (bucket_id, key, content_type, content_hash, size, filename, owner_id, is_public, status)
+                   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'pending')
+                   RETURNING id`, [
+                                    bucket.id,
+                                    s3Key,
+                                    contentType,
+                                    contentHash,
+                                    size,
+                                    filename || null,
+                                    bucket.owner_id,
+                                    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);
+                                const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
+                                // --- Track the upload request ---
+                                await pgClient.query(`INSERT INTO ${storageConfig.uploadRequestsQualifiedName}
+                   (file_id, bucket_id, key, content_type, content_hash, size, status, expires_at)
+                   VALUES ($1, $2, $3, $4, $5, $6, 'issued', $7)`, [fileId, bucket.id, s3Key, contentType, contentHash, size, expiresAt]);
+                                await pgClient.query('COMMIT');
+                                return {
+                                    uploadUrl,
+                                    fileId,
+                                    key: s3Key,
+                                    deduplicated: false,
+                                    expiresAt,
+                                };
+                            }
+                            catch (err) {
+                                await pgClient.query('ROLLBACK');
+                                throw err;
+                            }
+                        });
+                    });
+                },
+                confirmUpload(_$mutation, fieldArgs) {
+                    const $input = fieldArgs.getRaw('input');
+                    const $withPgClient = (0, grafast_1.context)().get('withPgClient');
+                    const $pgSettings = (0, grafast_1.context)().get('pgSettings');
+                    const $combined = (0, grafast_1.object)({
+                        input: $input,
+                        withPgClient: $withPgClient,
+                        pgSettings: $pgSettings,
+                    });
+                    return (0, grafast_1.lambda)($combined, async ({ input, withPgClient, pgSettings }) => {
+                        const { fileId } = input;
+                        if (!fileId || typeof fileId !== 'string') {
+                            throw new Error('INVALID_FILE_ID');
+                        }
+                        return withPgClient(pgSettings, async (pgClient) => {
+                            await pgClient.query('BEGIN');
+                            try {
+                                // --- Resolve storage module config ---
+                                const databaseId = await resolveDatabaseId(pgClient);
+                                if (!databaseId) {
+                                    throw new Error('DATABASE_NOT_FOUND');
+                                }
+                                const storageConfig = await (0, storage_module_cache_1.getStorageModuleConfig)(pgClient, databaseId);
+                                if (!storageConfig) {
+                                    throw new Error('STORAGE_MODULE_NOT_PROVISIONED');
+                                }
+                                // --- Look up the file (RLS enforced) ---
+                                const fileResult = await pgClient.query(`SELECT id, key, content_type, status, bucket_id
+                   FROM ${storageConfig.filesQualifiedName}
+                   WHERE id = $1
+                   LIMIT 1`, [fileId]);
+                                if (fileResult.rows.length === 0) {
+                                    throw new Error('FILE_NOT_FOUND');
+                                }
+                                const file = fileResult.rows[0];
+                                if (file.status !== 'pending') {
+                                    // File is already confirmed or processed — idempotent success
+                                    await pgClient.query('COMMIT');
+                                    return {
+                                        fileId: file.id,
+                                        status: file.status,
+                                        success: true,
+                                    };
+                                }
+                                // --- Verify file exists in S3 ---
+                                const s3Head = await (0, s3_signer_1.headObject)(s3, file.key, file.content_type);
+                                if (!s3Head) {
+                                    throw new Error('FILE_NOT_IN_S3: the file has not been uploaded yet');
+                                }
+                                // --- Content-type verification ---
+                                if (s3Head.contentType && s3Head.contentType !== file.content_type) {
+                                    // Mark upload_request as rejected
+                                    await pgClient.query(`UPDATE ${storageConfig.uploadRequestsQualifiedName}
+                     SET status = 'rejected'
+                     WHERE file_id = $1 AND status = 'issued'`, [fileId]);
+                                    await pgClient.query('COMMIT');
+                                    throw new Error(`CONTENT_TYPE_MISMATCH: expected ${file.content_type}, got ${s3Head.contentType}`);
+                                }
+                                // --- Transition file to 'ready' ---
+                                await pgClient.query(`UPDATE ${storageConfig.filesQualifiedName}
+                   SET status = 'ready'
+                   WHERE id = $1`, [fileId]);
+                                // --- Update upload_request to 'confirmed' ---
+                                await pgClient.query(`UPDATE ${storageConfig.uploadRequestsQualifiedName}
+                   SET status = 'confirmed', confirmed_at = NOW()
+                   WHERE file_id = $1 AND status = 'issued'`, [fileId]);
+                                await pgClient.query('COMMIT');
+                                return {
+                                    fileId: file.id,
+                                    status: 'ready',
+                                    success: true,
+                                };
+                            }
+                            catch (err) {
+                                await pgClient.query('ROLLBACK');
+                                throw err;
+                            }
+                        });
+                    });
+                },
+            },
+        },
+    }));
+}
+exports.PresignedUrlPlugin = createPresignedUrlPlugin;
+exports.default = exports.PresignedUrlPlugin;

package/preset.d.ts

@@ -0,0 +1,34 @@
+/**
+ * PostGraphile v5 Presigned URL Preset
+ *
+ * Provides a convenient preset for including presigned URL upload support
+ * in PostGraphile. Combines the main mutation plugin (requestUploadUrl,
+ * confirmUpload) with the downloadUrl computed field plugin.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PresignedUrlPluginOptions } from './types';
+/**
+ * Creates a preset that includes the presigned URL plugins with the given options.
+ *
+ * @example
+ * ```typescript
+ * import { PresignedUrlPreset } from 'graphile-presigned-url-plugin';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * const preset = {
+ *   extends: [
+ *     PresignedUrlPreset({
+ *       s3: {
+ *         client: s3Client,
+ *         bucket: 'my-bucket',
+ *         publicUrlPrefix: 'https://cdn.example.com',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export declare function PresignedUrlPreset(options: PresignedUrlPluginOptions): GraphileConfig.Preset;
+export default PresignedUrlPreset;

package/preset.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * PostGraphile v5 Presigned URL Preset
+ *
+ * Provides a convenient preset for including presigned URL upload support
+ * in PostGraphile. Combines the main mutation plugin (requestUploadUrl,
+ * confirmUpload) with the downloadUrl computed field plugin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PresignedUrlPreset = PresignedUrlPreset;
+const plugin_1 = require("./plugin");
+const download_url_field_1 = require("./download-url-field");
+/**
+ * Creates a preset that includes the presigned URL plugins with the given options.
+ *
+ * @example
+ * ```typescript
+ * import { PresignedUrlPreset } from 'graphile-presigned-url-plugin';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * const preset = {
+ *   extends: [
+ *     PresignedUrlPreset({
+ *       s3: {
+ *         client: s3Client,
+ *         bucket: 'my-bucket',
+ *         publicUrlPrefix: 'https://cdn.example.com',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+function PresignedUrlPreset(options) {
+    return {
+        plugins: [
+            (0, plugin_1.createPresignedUrlPlugin)(options),
+            (0, download_url_field_1.createDownloadUrlPlugin)(options),
+        ],
+    };
+}
+exports.default = PresignedUrlPreset;

package/s3-signer.d.ts

@@ -0,0 +1,44 @@
+import type { S3Config } from './types';
+/**
+ * Generate a presigned PUT URL for uploading a file to S3.
+ *
+ * The presigned URL is locked to the specific key, content-type, and
+ * content-length via the signature. The client MUST use these exact values
+ * when performing the PUT request.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key (content hash or UUID)
+ * @param contentType - MIME type (locked into the signature)
+ * @param contentLength - File size in bytes (locked into the signature)
+ * @param expiresIn - URL expiry in seconds (default: 900 = 15 minutes)
+ * @returns Presigned PUT URL
+ */
+export declare function generatePresignedPutUrl(s3Config: S3Config, key: string, contentType: string, contentLength: number, expiresIn?: number): Promise<string>;
+/**
+ * Generate a presigned GET URL for downloading a file from S3.
+ *
+ * Used for private files that shouldn't be served through a public CDN.
+ * For public files, the downloadUrl field returns the public URL prefix + key.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key
+ * @param expiresIn - URL expiry in seconds (default: 3600 = 1 hour)
+ * @param filename - Optional filename for Content-Disposition header
+ * @returns Presigned GET URL
+ */
+export declare function generatePresignedGetUrl(s3Config: S3Config, key: string, expiresIn?: number, filename?: string): Promise<string>;
+/**
+ * Check if an object exists in S3 and optionally verify its content-type.
+ *
+ * Used by confirmUpload to verify the file was actually uploaded to S3
+ * and that the content-type matches what was declared.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key
+ * @param expectedContentType - Expected MIME type (optional)
+ * @returns Object metadata if exists, null if not found
+ */
+export declare function headObject(s3Config: S3Config, key: string, expectedContentType?: string): Promise<{
+    contentType?: string;
+    contentLength?: number;
+} | null>;

package/s3-signer.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePresignedPutUrl = generatePresignedPutUrl;
+exports.generatePresignedGetUrl = generatePresignedGetUrl;
+exports.headObject = headObject;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('graphile-presigned-url:s3');
+/**
+ * Generate a presigned PUT URL for uploading a file to S3.
+ *
+ * The presigned URL is locked to the specific key, content-type, and
+ * content-length via the signature. The client MUST use these exact values
+ * when performing the PUT request.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key (content hash or UUID)
+ * @param contentType - MIME type (locked into the signature)
+ * @param contentLength - File size in bytes (locked into the signature)
+ * @param expiresIn - URL expiry in seconds (default: 900 = 15 minutes)
+ * @returns Presigned PUT URL
+ */
+async function generatePresignedPutUrl(s3Config, key, contentType, contentLength, expiresIn = 900) {
+    const command = new client_s3_1.PutObjectCommand({
+        Bucket: s3Config.bucket,
+        Key: key,
+        ContentType: contentType,
+        ContentLength: contentLength,
+    });
+    const url = await (0, s3_request_presigner_1.getSignedUrl)(s3Config.client, command, { expiresIn });
+    log.debug(`Generated presigned PUT URL for key=${key}, contentType=${contentType}, expires=${expiresIn}s`);
+    return url;
+}
+/**
+ * Generate a presigned GET URL for downloading a file from S3.
+ *
+ * Used for private files that shouldn't be served through a public CDN.
+ * For public files, the downloadUrl field returns the public URL prefix + key.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key
+ * @param expiresIn - URL expiry in seconds (default: 3600 = 1 hour)
+ * @param filename - Optional filename for Content-Disposition header
+ * @returns Presigned GET URL
+ */
+async function generatePresignedGetUrl(s3Config, key, expiresIn = 3600, filename) {
+    const params = {
+        Bucket: s3Config.bucket,
+        Key: key,
+    };
+    if (filename) {
+        const sanitized = filename.replace(/["\\\r\n]/g, '_');
+        params.ResponseContentDisposition = `attachment; filename="${sanitized}"`;
+    }
+    const command = new client_s3_1.GetObjectCommand(params);
+    const url = await (0, s3_request_presigner_1.getSignedUrl)(s3Config.client, command, { expiresIn });
+    log.debug(`Generated presigned GET URL for key=${key}, expires=${expiresIn}s`);
+    return url;
+}
+/**
+ * Check if an object exists in S3 and optionally verify its content-type.
+ *
+ * Used by confirmUpload to verify the file was actually uploaded to S3
+ * and that the content-type matches what was declared.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key
+ * @param expectedContentType - Expected MIME type (optional)
+ * @returns Object metadata if exists, null if not found
+ */
+async function headObject(s3Config, key, expectedContentType) {
+    try {
+        const response = await s3Config.client.send(new client_s3_1.HeadObjectCommand({
+            Bucket: s3Config.bucket,
+            Key: key,
+        }));
+        if (expectedContentType && response.ContentType !== expectedContentType) {
+            log.warn(`Content-type mismatch for key=${key}: expected=${expectedContentType}, actual=${response.ContentType}`);
+        }
+        return {
+            contentType: response.ContentType,
+            contentLength: response.ContentLength,
+        };
+    }
+    catch (e) {
+        if (e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404) {
+            return null;
+        }
+        throw e;
+    }
+}

package/storage-module-cache.d.ts

@@ -0,0 +1,40 @@
+import type { StorageModuleConfig, BucketConfig } from './types';
+/**
+ * Resolve the storage module config for a database, using the LRU cache.
+ *
+ * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
+ * @param databaseId - The metaschema database UUID
+ * @returns StorageModuleConfig or null if no storage module is provisioned
+ */
+export declare function getStorageModuleConfig(pgClient: {
+    query: (sql: string, params: unknown[]) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string): Promise<StorageModuleConfig | null>;
+/**
+ * Resolve bucket metadata for a given database + bucket key, using the LRU cache.
+ *
+ * On cache miss, queries the bucket table (RLS-enforced via pgSettings on
+ * the pgClient). On cache hit, returns the cached metadata directly.
+ *
+ * @param pgClient - A pg client from the Graphile context
+ * @param storageConfig - The resolved StorageModuleConfig for this database
+ * @param databaseId - The metaschema database UUID (used as cache key prefix)
+ * @param bucketKey - The bucket key (e.g., "public", "private")
+ * @returns BucketConfig or null if the bucket doesn't exist / isn't accessible
+ */
+export declare function getBucketConfig(pgClient: {
+    query: (sql: string, params: unknown[]) => Promise<{
+        rows: unknown[];
+    }>;
+}, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: string): Promise<BucketConfig | null>;
+/**
+ * Clear the storage module cache AND bucket cache.
+ * Useful for testing or schema changes.
+ */
+export declare function clearStorageModuleCache(): void;
+/**
+ * Clear cached bucket entries for a specific database.
+ * Useful when bucket config changes are detected.
+ */
+export declare function clearBucketCache(databaseId?: string): void;