graphile-presigned-url-plugin 0.10.0 → 0.12.0

package/esm/plugin.js

@@ -1,48 +1,42 @@
 /**
- * Presigned URL Plugin for PostGraphile v5
+ * Per-Table Storage Middleware Plugin for PostGraphile v5
  *
- * Adds presigned URL upload support to PostGraphile v5:
+ * Hooks into PostGraphile's auto-generated CRUD mutations to add S3 operations:
  *
- * 1. `requestUploadUrl` mutation — generates a presigned PUT URL for direct
- *    client-to-S3 upload. Checks bucket access via RLS, deduplicates by
- *    content hash via UNIQUE(bucket_id, key) constraint.
+ * 1. Delete middleware — wraps `delete*` mutations on `@storageFiles`-tagged tables
+ *    with S3 object cleanup (sync + async GC fallback via AFTER DELETE trigger).
  *
- * 2. `downloadUrl` computed field on File types — generates presigned GET URLs
- *    for private files, returns public URL prefix + key for public files.
+ * 2. Upload fields — adds `requestUploadUrl` and `requestBulkUploadUrls` fields
+ *    on `@storageBuckets`-tagged types, so clients upload via the typed bucket API.
  *
- * Uses the extendSchema + grafast plan pattern (same as PublicKeySignature).
+ * 3. Mutation entry points — adds per-bucket mutation fields on the root Mutation
+ *    type (e.g., `appBucket(key: "public"): AppBucket`), so upload operations
+ *    can be accessed as proper GraphQL mutations instead of queries.
+ *
+ * 4. downloadUrl — handled by download-url-field.ts (separate plugin).
+ *
+ * Scope resolution uses the codec's schema/table name matched against
+ * cached storage module configs.
  */
-import { context as grafastContext, lambda, object } from 'grafast';
-import { extendSchema, gql } from 'graphile-utils';
+import { access, context as grafastContext, lambda, object } from 'grafast';
+import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
-import { getStorageModuleConfig, getStorageModuleConfigForOwner, getBucketConfig, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
-import { generatePresignedPutUrl } from './s3-signer';
+import { loadAllStorageModules, resolveStorageConfigFromCodec, getBucketConfig, isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
+import { generatePresignedPutUrl, deleteS3Object } from './s3-signer';
 const log = new Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
 const MAX_CONTENT_HASH_LENGTH = 128;
 const MAX_CONTENT_TYPE_LENGTH = 255;
-const MAX_BUCKET_KEY_LENGTH = 255;
 const MAX_CUSTOM_KEY_LENGTH = 1024;
 const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/;
 const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_.\-\/]*$/;
 // --- Helpers ---
-/**
- * Validate a SHA-256 hex string.
- */
 function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
 }
-/**
- * Build the S3 key from content hash.
- * Format: {contentHash} (flat namespace, content-addressed)
- */
 function buildS3Key(contentHash) {
     return contentHash;
 }
-/**
- * Validate a custom S3 key.
- * Must be 1-1024 chars, no path traversal, no leading slash, no null bytes.
- */
 function validateCustomKey(key) {
     if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
         return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
@@ -61,11 +55,6 @@ function validateCustomKey(key) {
     }
     return null;
 }
-/**
- * Derive an ltree path from a custom S3 key's directory portion.
- * e.g., "reports/2024/Q1/revenue.pdf" → "reports.2024.Q1"
- * Returns null if the key has no directory component.
- */
 function derivePathFromKey(key) {
     const lastSlash = key.lastIndexOf('/');
     if (lastSlash <= 0)
@@ -73,41 +62,20 @@ function derivePathFromKey(key) {
     const dir = key.substring(0, lastSlash);
     return dir.replace(/\//g, '.');
 }
-/**
- * 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({
         text: `SELECT jwt_private.current_database_id() AS id`,
     });
     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
@@ -123,16 +91,6 @@ function resolveS3ForDatabase(options, storageConfig, databaseId) {
         ...(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;
@@ -143,209 +101,403 @@ async function ensureS3BucketExists(options, s3BucketName, bucket, databaseId, a
     markS3BucketProvisioned(s3BucketName);
     log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
 }
+// --- Plugin factory ---
 export function createPresignedUrlPlugin(options) {
-    return extendSchema(() => ({
-        typeDefs: gql `
-      input RequestUploadUrlInput {
-        """Bucket key (e.g., "public", "private")"""
-        bucketKey: String!
-        """
-        Owner entity ID for entity-scoped uploads.
-        Omit for app-level (database-wide) storage.
-        When provided, resolves the storage module for the entity type
-        that owns this entity instance (e.g., a data room ID, team ID).
-        """
-        ownerId: UUID
-        """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
-        """
-        Custom S3 key (e.g., "reports/2024/Q1.pdf").
-        Only allowed when the bucket has allow_custom_keys=true.
-        When omitted, key defaults to contentHash (content-addressed dedup).
-        When provided, the file is stored at this key.
-        Re-uploading to an existing key auto-creates a new version.
-        """
-        key: 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
-        """ID of the previous version (set when re-uploading to an existing custom key)"""
-        previousVersionId: UUID
-      }
-
-      input BulkUploadFileInput {
-        """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
-        """Custom S3 key (only when bucket has allow_custom_keys=true)"""
-        key: String
-      }
-
-      input RequestBulkUploadUrlsInput {
-        """Bucket key (e.g., "public", "private")"""
-        bucketKey: String!
-        """Owner entity ID for entity-scoped uploads"""
-        ownerId: UUID
-        """Array of files to upload"""
-        files: [BulkUploadFileInput!]!
-      }
-
-      type BulkUploadFilePayload {
-        """Presigned PUT URL (null if file was deduplicated)"""
-        uploadUrl: String
-        """The file ID"""
-        fileId: UUID!
-        """The S3 object key"""
-        key: String!
-        """Whether this file was deduplicated"""
-        deduplicated: Boolean!
-        """Presigned URL expiry time (null if deduplicated)"""
-        expiresAt: Datetime
-        """ID of the previous version (set when re-uploading to an existing custom key)"""
-        previousVersionId: UUID
-        """Index of this file in the input array (for client correlation)"""
-        index: Int!
-      }
-
-      type RequestBulkUploadUrlsPayload {
-        """Array of results, one per input file"""
-        files: [BulkUploadFilePayload!]!
-      }
-
-      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
-
-        """
-        Request presigned URLs for uploading multiple files in a single batch.
-        Subject to per-storage-module limits (max_bulk_files, max_bulk_total_size).
-        Each file is processed independently — some may dedup while others get fresh URLs.
-        """
-        requestBulkUploadUrls(
-          input: RequestBulkUploadUrlsInput!
-        ): RequestBulkUploadUrlsPayload
-      }
-    `,
-        plans: {
-            Mutation: {
-                requestUploadUrl(_$mutation, fieldArgs) {
-                    const $input = fieldArgs.getRaw('input');
-                    const $withPgClient = grafastContext().get('withPgClient');
-                    const $pgSettings = grafastContext().get('pgSettings');
-                    const $combined = object({
-                        input: $input,
-                        withPgClient: $withPgClient,
-                        pgSettings: $pgSettings,
+    return {
+        name: 'PresignedUrlPlugin',
+        version: '1.0.0',
+        description: 'Per-table S3 storage middleware: upload fields on @storageBuckets, delete middleware on @storageFiles',
+        after: ['PgAttributesPlugin', 'PgMutationCreatePlugin', 'PgMutationUpdateDeletePlugin'],
+        schema: {
+            hooks: {
+                /**
+                 * Add requestUploadUrl and requestBulkUploadUrls fields on @storageBuckets types.
+                 */
+                GraphQLObjectType_fields(fields, build, context) {
+                    const { scope: { pgCodec, isPgClassType, isRootMutation }, } = context;
+                    // --- Path 1: Add per-bucket mutation entry points on root Mutation ---
+                    if (isRootMutation) {
+                        const { graphql: { GraphQLString, GraphQLNonNull }, } = build;
+                        const bucketCodecs = Object.values(build.input.pgRegistry.pgCodecs).filter((codec) => codec.attributes && codec.extensions?.tags?.storageBuckets);
+                        if (bucketCodecs.length === 0)
+                            return fields;
+                        const newFields = {};
+                        for (const codec of bucketCodecs) {
+                            const typeName = build.inflection.tableType(codec);
+                            const bucketType = build.getTypeByName(typeName);
+                            if (!bucketType) {
+                                log.debug(`Skipping mutation entry point for ${codec.name}: type ${typeName} not found`);
+                                continue;
+                            }
+                            const fieldName = typeName.charAt(0).toLowerCase() + typeName.slice(1);
+                            const hasOwnerId = !!codec.attributes.owner_id;
+                            const capturedCodec = codec;
+                            log.debug(`Adding mutation entry point "${fieldName}" for bucket type ${typeName} (entity-scoped=${hasOwnerId})`);
+                            newFields[fieldName] = context.fieldWithHooks({ fieldName }, {
+                                description: `Look up a ${typeName} by key for mutation operations (upload, etc.).`,
+                                type: bucketType,
+                                args: {
+                                    key: { type: new GraphQLNonNull(GraphQLString), description: 'Bucket key (e.g., "public", "private")' },
+                                    ...(hasOwnerId
+                                        ? { ownerId: { type: new GraphQLNonNull(GraphQLString), description: 'Owner entity ID (required for entity-scoped buckets)' } }
+                                        : {}),
+                                },
+                                plan(_$mutation, fieldArgs) {
+                                    const $key = fieldArgs.getRaw('key');
+                                    const $ownerId = hasOwnerId ? fieldArgs.getRaw('ownerId') : lambda(null, () => null);
+                                    const $withPgClient = grafastContext().get('withPgClient');
+                                    const $pgSettings = grafastContext().get('pgSettings');
+                                    const $combined = object({
+                                        key: $key,
+                                        ownerId: $ownerId,
+                                        withPgClient: $withPgClient,
+                                        pgSettings: $pgSettings,
+                                    });
+                                    const $row = lambda($combined, async (vals) => {
+                                        return vals.withPgClient(vals.pgSettings, async (pgClient) => {
+                                            const databaseId = await resolveDatabaseId(pgClient);
+                                            if (!databaseId)
+                                                throw new Error('DATABASE_NOT_FOUND');
+                                            const allConfigs = await loadAllStorageModules(pgClient, databaseId);
+                                            const storageConfig = resolveStorageConfigFromCodec(capturedCodec, allConfigs);
+                                            if (!storageConfig)
+                                                throw new Error('STORAGE_MODULE_NOT_FOUND');
+                                            const bucket = await getBucketConfig(pgClient, storageConfig, databaseId, vals.key, vals.ownerId ?? undefined);
+                                            if (!bucket)
+                                                throw new Error('BUCKET_NOT_FOUND');
+                                            return bucket;
+                                        });
+                                    });
+                                    const columnEntries = {};
+                                    for (const col of Object.keys(capturedCodec.attributes)) {
+                                        columnEntries[col] = access($row, col);
+                                    }
+                                    return object(columnEntries);
+                                },
+                            });
+                        }
+                        return build.extend(fields, newFields, 'PresignedUrlPlugin adding per-bucket mutation entry points');
+                    }
+                    // --- Path 2: Add upload fields on @storageBuckets types ---
+                    if (!isPgClassType || !pgCodec || !pgCodec.attributes) {
+                        return fields;
+                    }
+                    const tags = pgCodec.extensions?.tags;
+                    if (!tags?.storageBuckets) {
+                        return fields;
+                    }
+                    log.debug(`Adding upload fields to bucket type: ${pgCodec.name} (has @storageBuckets tag)`);
+                    const { graphql: { GraphQLString, GraphQLNonNull, GraphQLInt, GraphQLBoolean, GraphQLObjectType, GraphQLList, GraphQLInputObjectType, }, } = build;
+                    // --- Shared output types ---
+                    const UploadUrlPayloadType = new GraphQLObjectType({
+                        name: `${build.inflection.upperCamelCase(pgCodec.name)}RequestUploadUrlPayload`,
+                        fields: {
+                            uploadUrl: { type: GraphQLString, description: 'Presigned PUT URL (null if deduplicated)' },
+                            fileId: { type: new GraphQLNonNull(GraphQLString), description: 'The file ID' },
+                            key: { type: new GraphQLNonNull(GraphQLString), description: 'The S3 object key' },
+                            deduplicated: { type: new GraphQLNonNull(GraphQLBoolean), description: 'Whether this file was deduplicated' },
+                            expiresAt: { type: GraphQLString, description: 'Presigned URL expiry time (null if deduplicated)' },
+                            previousVersionId: { type: GraphQLString, description: 'ID of the previous version' },
+                        },
                     });
-                    return lambda($combined, async ({ input, withPgClient, pgSettings }) => {
-                        const result = await processUpload(options, input, withPgClient, pgSettings);
-                        return result;
+                    const BulkUploadFilePayloadType = new GraphQLObjectType({
+                        name: `${build.inflection.upperCamelCase(pgCodec.name)}BulkUploadFilePayload`,
+                        fields: {
+                            uploadUrl: { type: GraphQLString },
+                            fileId: { type: new GraphQLNonNull(GraphQLString) },
+                            key: { type: new GraphQLNonNull(GraphQLString) },
+                            deduplicated: { type: new GraphQLNonNull(GraphQLBoolean) },
+                            expiresAt: { type: GraphQLString },
+                            previousVersionId: { type: GraphQLString },
+                            index: { type: new GraphQLNonNull(GraphQLInt), description: 'Index in the input array' },
+                        },
                     });
-                },
-                requestBulkUploadUrls(_$mutation, fieldArgs) {
-                    const $input = fieldArgs.getRaw('input');
-                    const $withPgClient = grafastContext().get('withPgClient');
-                    const $pgSettings = grafastContext().get('pgSettings');
-                    const $combined = object({
-                        input: $input,
-                        withPgClient: $withPgClient,
-                        pgSettings: $pgSettings,
+                    const BulkUploadUrlsPayloadType = new GraphQLObjectType({
+                        name: `${build.inflection.upperCamelCase(pgCodec.name)}RequestBulkUploadUrlsPayload`,
+                        fields: {
+                            files: { type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(BulkUploadFilePayloadType))) },
+                        },
                     });
-                    return lambda($combined, async ({ input, withPgClient, pgSettings }) => {
-                        const { bucketKey, ownerId, files } = input;
-                        if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
-                            throw new Error('INVALID_BUCKET_KEY');
-                        }
-                        if (!Array.isArray(files) || files.length === 0) {
-                            throw new Error('INVALID_FILES: must provide at least one file');
-                        }
-                        return withPgClient(pgSettings, async (pgClient) => {
-                            return pgClient.withTransaction(async (txClient) => {
-                                const databaseId = await resolveDatabaseId(txClient);
-                                if (!databaseId) {
-                                    throw new Error('DATABASE_NOT_FOUND');
-                                }
-                                const storageConfig = ownerId
-                                    ? await getStorageModuleConfigForOwner(txClient, databaseId, ownerId)
-                                    : await getStorageModuleConfig(txClient, databaseId);
-                                if (!storageConfig) {
-                                    throw new Error(ownerId
-                                        ? 'STORAGE_MODULE_NOT_FOUND_FOR_OWNER: no storage module found for the given ownerId'
-                                        : 'STORAGE_MODULE_NOT_PROVISIONED');
-                                }
-                                // --- Validate bulk limits ---
-                                if (files.length > storageConfig.maxBulkFiles) {
-                                    throw new Error(`BULK_LIMIT_EXCEEDED: max ${storageConfig.maxBulkFiles} files per batch`);
-                                }
-                                const totalSize = files.reduce((sum, f) => sum + (f.size || 0), 0);
-                                if (totalSize > storageConfig.maxBulkTotalSize) {
-                                    throw new Error(`BULK_SIZE_EXCEEDED: total size ${totalSize} exceeds max ${storageConfig.maxBulkTotalSize} bytes`);
-                                }
-                                const bucket = await getBucketConfig(txClient, storageConfig, databaseId, bucketKey, ownerId);
-                                if (!bucket) {
-                                    throw new Error('BUCKET_NOT_FOUND');
+                    const BulkUploadFileInputType = new GraphQLInputObjectType({
+                        name: `${build.inflection.upperCamelCase(pgCodec.name)}BulkUploadFileInput`,
+                        fields: {
+                            contentHash: { type: new GraphQLNonNull(GraphQLString) },
+                            contentType: { type: new GraphQLNonNull(GraphQLString) },
+                            size: { type: new GraphQLNonNull(GraphQLInt) },
+                            filename: { type: GraphQLString },
+                            key: { type: GraphQLString },
+                        },
+                    });
+                    // Capture codec for closure
+                    const capturedCodec = pgCodec;
+                    return build.extend(fields, {
+                        requestUploadUrl: context.fieldWithHooks({ fieldName: 'requestUploadUrl' }, {
+                            description: 'Request a presigned URL for uploading a file to this bucket.',
+                            type: UploadUrlPayloadType,
+                            args: {
+                                contentHash: { type: new GraphQLNonNull(GraphQLString), description: 'SHA-256 content hash (hex-encoded, 64 chars)' },
+                                contentType: { type: new GraphQLNonNull(GraphQLString), description: 'MIME type of the file' },
+                                size: { type: new GraphQLNonNull(GraphQLInt), description: 'File size in bytes' },
+                                filename: { type: GraphQLString, description: 'Original filename (optional)' },
+                                key: { type: GraphQLString, description: 'Custom S3 key (only when bucket has allow_custom_keys=true)' },
+                            },
+                            plan($parent, fieldArgs) {
+                                const $bucketId = $parent.get('id');
+                                const $bucketKey = $parent.get('key');
+                                const $bucketType = $parent.get('type');
+                                const $bucketIsPublic = $parent.get('is_public');
+                                const $bucketAllowCustomKeys = $parent.get('allow_custom_keys');
+                                const $bucketAllowedMimeTypes = $parent.get('allowed_mime_types');
+                                const $bucketMaxFileSize = $parent.get('max_file_size');
+                                const $bucketOwnerId = capturedCodec.attributes.owner_id ? $parent.get('owner_id') : lambda(null, () => null);
+                                const $contentHash = fieldArgs.getRaw('contentHash');
+                                const $contentType = fieldArgs.getRaw('contentType');
+                                const $size = fieldArgs.getRaw('size');
+                                const $filename = fieldArgs.getRaw('filename');
+                                const $customKey = fieldArgs.getRaw('key');
+                                const $withPgClient = grafastContext().get('withPgClient');
+                                const $pgSettings = grafastContext().get('pgSettings');
+                                const $combined = object({
+                                    bucketId: $bucketId,
+                                    bucketKey: $bucketKey,
+                                    bucketType: $bucketType,
+                                    bucketIsPublic: $bucketIsPublic,
+                                    bucketAllowCustomKeys: $bucketAllowCustomKeys,
+                                    bucketAllowedMimeTypes: $bucketAllowedMimeTypes,
+                                    bucketMaxFileSize: $bucketMaxFileSize,
+                                    bucketOwnerId: $bucketOwnerId,
+                                    contentHash: $contentHash,
+                                    contentType: $contentType,
+                                    size: $size,
+                                    filename: $filename,
+                                    customKey: $customKey,
+                                    withPgClient: $withPgClient,
+                                    pgSettings: $pgSettings,
+                                });
+                                return lambda($combined, async (vals) => {
+                                    return vals.withPgClient(vals.pgSettings, async (pgClient) => {
+                                        return pgClient.withTransaction(async (txClient) => {
+                                            const databaseId = await resolveDatabaseId(txClient);
+                                            if (!databaseId)
+                                                throw new Error('DATABASE_NOT_FOUND');
+                                            const allConfigs = await loadAllStorageModules(txClient, databaseId);
+                                            const storageConfig = resolveStorageConfigFromCodec(capturedCodec, allConfigs);
+                                            if (!storageConfig)
+                                                throw new Error('STORAGE_MODULE_NOT_FOUND');
+                                            const bucket = {
+                                                id: vals.bucketId,
+                                                key: vals.bucketKey,
+                                                type: vals.bucketType,
+                                                is_public: vals.bucketIsPublic,
+                                                owner_id: vals.bucketOwnerId,
+                                                allowed_mime_types: vals.bucketAllowedMimeTypes,
+                                                max_file_size: vals.bucketMaxFileSize,
+                                                allow_custom_keys: vals.bucketAllowCustomKeys ?? false,
+                                            };
+                                            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+                                            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
+                                            return processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
+                                                contentHash: vals.contentHash,
+                                                contentType: vals.contentType,
+                                                size: vals.size,
+                                                filename: vals.filename,
+                                                key: vals.customKey,
+                                            });
+                                        });
+                                    });
+                                });
+                            },
+                        }),
+                        requestBulkUploadUrls: context.fieldWithHooks({ fieldName: 'requestBulkUploadUrls' }, {
+                            description: 'Request presigned URLs for uploading multiple files to this bucket.',
+                            type: BulkUploadUrlsPayloadType,
+                            args: {
+                                files: {
+                                    type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(BulkUploadFileInputType))),
+                                    description: 'Array of files to upload',
+                                },
+                            },
+                            plan($parent, fieldArgs) {
+                                const $bucketId = $parent.get('id');
+                                const $bucketKey = $parent.get('key');
+                                const $bucketType = $parent.get('type');
+                                const $bucketIsPublic = $parent.get('is_public');
+                                const $bucketAllowCustomKeys = $parent.get('allow_custom_keys');
+                                const $bucketAllowedMimeTypes = $parent.get('allowed_mime_types');
+                                const $bucketMaxFileSize = $parent.get('max_file_size');
+                                const $bucketOwnerId = capturedCodec.attributes.owner_id ? $parent.get('owner_id') : lambda(null, () => null);
+                                const $files = fieldArgs.getRaw('files');
+                                const $withPgClient = grafastContext().get('withPgClient');
+                                const $pgSettings = grafastContext().get('pgSettings');
+                                const $combined = object({
+                                    bucketId: $bucketId,
+                                    bucketKey: $bucketKey,
+                                    bucketType: $bucketType,
+                                    bucketIsPublic: $bucketIsPublic,
+                                    bucketAllowCustomKeys: $bucketAllowCustomKeys,
+                                    bucketAllowedMimeTypes: $bucketAllowedMimeTypes,
+                                    bucketMaxFileSize: $bucketMaxFileSize,
+                                    bucketOwnerId: $bucketOwnerId,
+                                    files: $files,
+                                    withPgClient: $withPgClient,
+                                    pgSettings: $pgSettings,
+                                });
+                                return lambda($combined, async (vals) => {
+                                    const { files } = vals;
+                                    if (!Array.isArray(files) || files.length === 0) {
+                                        throw new Error('INVALID_FILES: must provide at least one file');
+                                    }
+                                    return vals.withPgClient(vals.pgSettings, async (pgClient) => {
+                                        return pgClient.withTransaction(async (txClient) => {
+                                            const databaseId = await resolveDatabaseId(txClient);
+                                            if (!databaseId)
+                                                throw new Error('DATABASE_NOT_FOUND');
+                                            const allConfigs = await loadAllStorageModules(txClient, databaseId);
+                                            const storageConfig = resolveStorageConfigFromCodec(capturedCodec, allConfigs);
+                                            if (!storageConfig)
+                                                throw new Error('STORAGE_MODULE_NOT_FOUND');
+                                            if (files.length > storageConfig.maxBulkFiles) {
+                                                throw new Error(`BULK_LIMIT_EXCEEDED: max ${storageConfig.maxBulkFiles} files per batch`);
+                                            }
+                                            const totalSize = files.reduce((sum, f) => sum + (f.size || 0), 0);
+                                            if (totalSize > storageConfig.maxBulkTotalSize) {
+                                                throw new Error(`BULK_SIZE_EXCEEDED: total size ${totalSize} exceeds max ${storageConfig.maxBulkTotalSize} bytes`);
+                                            }
+                                            const bucket = {
+                                                id: vals.bucketId,
+                                                key: vals.bucketKey,
+                                                type: vals.bucketType,
+                                                is_public: vals.bucketIsPublic,
+                                                owner_id: vals.bucketOwnerId,
+                                                allowed_mime_types: vals.bucketAllowedMimeTypes,
+                                                max_file_size: vals.bucketMaxFileSize,
+                                                allow_custom_keys: vals.bucketAllowCustomKeys ?? false,
+                                            };
+                                            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+                                            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
+                                            const results = [];
+                                            for (let i = 0; i < files.length; i++) {
+                                                const result = await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, files[i]);
+                                                results.push({ ...result, index: i });
+                                            }
+                                            return { files: results };
+                                        });
+                                    });
+                                });
+                            },
+                        }),
+                    }, `PresignedUrlPlugin adding upload fields to ${pgCodec.name}`);
+                },
+                /**
+                 * Wrap delete* mutations on @storageFiles-tagged tables with S3 cleanup.
+                 *
+                 * Pattern: identical to graphile-bucket-provisioner-plugin's create/update hooks.
+                 * 1. Read the file row BEFORE delete (need key + bucket_id for S3 cleanup)
+                 * 2. Call PostGraphile's generated delete (RLS enforced)
+                 * 3. If delete succeeded, check refcount and attempt sync S3 delete
+                 * 4. AFTER DELETE trigger (constructive-db) enqueues async GC job as fallback
+                 */
+                GraphQLObjectType_fields_field(field, build, context) {
+                    const { scope: { isRootMutation, fieldName, pgCodec }, } = context;
+                    if (!isRootMutation || !pgCodec || !pgCodec.attributes) {
+                        return field;
+                    }
+                    const tags = pgCodec.extensions?.tags;
+                    if (!tags?.storageFiles) {
+                        return field;
+                    }
+                    if (!fieldName.startsWith('delete')) {
+                        return field;
+                    }
+                    log.debug(`Wrapping delete mutation "${fieldName}" with S3 cleanup (codec: ${pgCodec.name})`);
+                    const defaultResolver = (obj) => obj[fieldName];
+                    const { resolve: oldResolve = defaultResolver, ...rest } = field;
+                    const capturedCodec = pgCodec;
+                    return {
+                        ...rest,
+                        async resolve(source, args, graphqlContext, info) {
+                            // Extract the file ID from the mutation input
+                            const inputKey = Object.keys(args.input || {}).find((k) => k !== 'clientMutationId');
+                            const fileInput = inputKey ? args.input[inputKey] : null;
+                            let fileRow = null;
+                            if (fileInput) {
+                                // Read the file row BEFORE delete to get the S3 key + bucket_id
+                                const withPgClient = graphqlContext.withPgClient;
+                                const pgSettings = graphqlContext.pgSettings;
+                                if (withPgClient) {
+                                    try {
+                                        await withPgClient(pgSettings, async (pgClient) => {
+                                            const databaseId = await resolveDatabaseId(pgClient);
+                                            if (!databaseId)
+                                                return;
+                                            const allConfigs = await loadAllStorageModules(pgClient, databaseId);
+                                            const storageConfig = resolveStorageConfigFromCodec(capturedCodec, allConfigs);
+                                            if (!storageConfig)
+                                                return;
+                                            // Read the file row (RLS enforced)
+                                            const result = await pgClient.query({
+                                                text: `SELECT key, bucket_id FROM ${storageConfig.filesQualifiedName} WHERE id = $1 LIMIT 1`,
+                                                values: [fileInput],
+                                            });
+                                            if (result.rows.length > 0) {
+                                                fileRow = result.rows[0];
+                                            }
+                                        });
+                                    }
+                                    catch (err) {
+                                        log.warn(`Pre-delete file lookup failed: ${err.message}`);
+                                    }
                                 }
-                                // --- Ensure S3 bucket exists once for the batch ---
-                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
-                                await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-                                // --- Process each file ---
-                                const results = [];
-                                for (let i = 0; i < files.length; i++) {
-                                    const fileInput = files[i];
-                                    const singleInput = {
-                                        ...fileInput,
-                                        bucketKey,
-                                        ownerId,
-                                    };
-                                    const result = await processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, singleInput);
-                                    results.push({ ...result, index: i });
+                            }
+                            // Call PostGraphile's generated delete (RLS enforced)
+                            const result = await oldResolve(source, args, graphqlContext, info);
+                            // Attempt sync S3 cleanup if we have the file row
+                            if (fileRow) {
+                                const withPgClient = graphqlContext.withPgClient;
+                                const pgSettings = graphqlContext.pgSettings;
+                                if (withPgClient) {
+                                    try {
+                                        await withPgClient(pgSettings, async (pgClient) => {
+                                            const databaseId = await resolveDatabaseId(pgClient);
+                                            if (!databaseId)
+                                                return;
+                                            const allConfigs = await loadAllStorageModules(pgClient, databaseId);
+                                            const storageConfig = resolveStorageConfigFromCodec(capturedCodec, allConfigs);
+                                            if (!storageConfig)
+                                                return;
+                                            // Check refcount: any other file with the same key in this bucket?
+                                            const refResult = await pgClient.query({
+                                                text: `SELECT COUNT(*)::int AS ref_count FROM ${storageConfig.filesQualifiedName} WHERE key = $1 AND bucket_id = $2`,
+                                                values: [fileRow.key, fileRow.bucket_id],
+                                            });
+                                            const refCount = refResult.rows[0]?.ref_count ?? 0;
+                                            if (refCount > 0) {
+                                                log.info(`File deleted from DB; S3 key ${fileRow.key} still referenced by ${refCount} file(s)`);
+                                                return;
+                                            }
+                                            // No other references — attempt sync S3 delete
+                                            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
+                                            await deleteS3Object(s3ForDb, fileRow.key);
+                                            log.info(`Sync S3 delete succeeded for key=${fileRow.key}`);
+                                        });
+                                    }
+                                    catch (err) {
+                                        // Sync S3 delete failed — the AFTER DELETE trigger has enqueued an async GC job
+                                        log.warn(`Sync S3 delete failed for key=${fileRow.key}; async GC job will retry: ${err.message}`);
+                                    }
                                 }
-                                return { files: results };
-                            });
-                        });
-                    });
+                            }
+                            return result;
+                        },
+                    };
                 },
             },
         },
-    }));
+    };
 }
 // --- Shared upload logic ---
-/**
- * Process a single upload request (used by both requestUploadUrl and requestBulkUploadUrls).
- */
-async function processUpload(options, input, withPgClient, pgSettings) {
-    const { bucketKey, ownerId, contentHash, contentType, size, filename, key: customKey } = input;
-    if (!bucketKey || typeof bucketKey !== 'string' || bucketKey.length > MAX_BUCKET_KEY_LENGTH) {
-        throw new Error('INVALID_BUCKET_KEY');
-    }
+async function processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, input) {
+    const { contentHash, contentType, size, filename, key: customKey } = input;
     if (!contentHash || typeof contentHash !== 'string' || contentHash.length > MAX_CONTENT_HASH_LENGTH) {
         throw new Error('INVALID_CONTENT_HASH');
     }
@@ -355,51 +507,6 @@ async function processUpload(options, input, withPgClient, pgSettings) {
     if (!contentType || typeof contentType !== 'string' || contentType.length > MAX_CONTENT_TYPE_LENGTH) {
         throw new Error('INVALID_CONTENT_TYPE');
     }
-    return withPgClient(pgSettings, async (pgClient) => {
-        return pgClient.withTransaction(async (txClient) => {
-            const databaseId = await resolveDatabaseId(txClient);
-            if (!databaseId) {
-                throw new Error('DATABASE_NOT_FOUND');
-            }
-            const storageConfig = ownerId
-                ? await getStorageModuleConfigForOwner(txClient, databaseId, ownerId)
-                : await getStorageModuleConfig(txClient, databaseId);
-            if (!storageConfig) {
-                throw new Error(ownerId
-                    ? 'STORAGE_MODULE_NOT_FOUND_FOR_OWNER: no storage module found for the given ownerId'
-                    : 'STORAGE_MODULE_NOT_PROVISIONED');
-            }
-            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');
-                }
-            }
-            const bucket = await getBucketConfig(txClient, storageConfig, databaseId, bucketKey, ownerId);
-            if (!bucket) {
-                throw new Error('BUCKET_NOT_FOUND');
-            }
-            const s3ForDb = resolveS3ForDatabase(options, storageConfig, databaseId);
-            await ensureS3BucketExists(options, s3ForDb.bucket, bucket, databaseId, storageConfig.allowedOrigins);
-            return processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, input);
-        });
-    });
-}
-/**
- * Process a single file upload within an already-resolved context.
- * Handles dedup, custom keys, versioning, and auto-path derivation.
- */
-async function processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, input) {
-    const { contentHash, contentType, size, filename, key: customKey } = input;
-    // --- Validate inputs ---
-    if (!contentHash || !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');
-    }
     if (typeof size !== 'number' || size <= 0 || size > storageConfig.defaultMaxFileSize) {
         throw new Error(`INVALID_FILE_SIZE: must be between 1 and ${storageConfig.defaultMaxFileSize} bytes`);
     }
@@ -408,7 +515,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
             throw new Error('INVALID_FILENAME');
         }
     }
-    // --- Validate content type against bucket's allowed_mime_types ---
+    // 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) => {
@@ -424,11 +531,11 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
             throw new Error(`CONTENT_TYPE_NOT_ALLOWED: ${contentType} not in bucket allowed types`);
         }
     }
-    // --- Validate size against bucket's max_file_size ---
+    // 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`);
     }
-    // --- Determine S3 key ---
+    // Determine S3 key
     let s3Key;
     let isCustomKey = false;
     if (customKey) {
@@ -445,11 +552,9 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     else {
         s3Key = buildS3Key(contentHash);
     }
-    // --- Dedup / versioning check ---
+    // Dedup / versioning check
     let previousVersionId = null;
     if (isCustomKey) {
-        // Custom key mode: check if a file with this key already exists in this bucket.
-        // If so, auto-version by linking via previous_version_id.
         const existingResult = await txClient.query({
             text: `SELECT id, content_hash
        FROM ${storageConfig.filesQualifiedName}
@@ -461,7 +566,6 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         });
         if (existingResult.rows.length > 0) {
             const existing = existingResult.rows[0];
-            // Same content hash = true dedup (no new upload needed)
             if (existing.content_hash === contentHash) {
                 log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
                 return {
@@ -473,13 +577,11 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
                     previousVersionId: null,
                 };
             }
-            // Different content = new version
             previousVersionId = existing.id;
             log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
         }
     }
     else {
-        // Hash-based mode: dedup by content_hash in this bucket
         const dedupResult = await txClient.query({
             text: `SELECT id
        FROM ${storageConfig.filesQualifiedName}
@@ -501,27 +603,23 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
             };
         }
     }
-    // --- Auto-derive ltree path from custom key directory (only when has_path_shares) ---
+    // Auto-derive ltree path from custom key directory (only when has_path_shares)
     const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
-    // --- Create file record ---
+    // Create file record
     const hasOwnerColumn = storageConfig.membershipType !== null;
     const columns = ['bucket_id', 'key', 'content_hash', 'mime_type', 'size', 'filename', 'is_public'];
     const values = [bucket.id, s3Key, contentHash, contentType, size, filename || null, bucket.is_public];
-    let paramIdx = values.length;
     if (hasOwnerColumn) {
         columns.push('owner_id');
         values.push(bucket.owner_id);
-        paramIdx = values.length;
     }
     if (previousVersionId) {
         columns.push('previous_version_id');
         values.push(previousVersionId);
-        paramIdx = values.length;
     }
     if (derivedPath) {
         columns.push('path');
         values.push(derivedPath);
-        paramIdx = values.length;
     }
     const placeholders = values.map((_, i) => `$${i + 1}`).join(', ');
     const fileResult = await txClient.query({
@@ -532,7 +630,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         values,
     });
     const fileId = fileResult.rows[0].id;
-    // --- Generate presigned PUT URL ---
+    // Generate presigned PUT URL
     const uploadUrl = await generatePresignedPutUrl(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
     const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();
     return {