graphile-presigned-url-plugin 1.13.1 → 1.14.1

package/custom-key.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+export declare function validateCustomKey(key: string): string | null;

package/custom-key.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCustomKey = validateCustomKey;
+const MAX_CUSTOM_KEY_LENGTH = 1024;
+/**
+ * The key alphabet. A leading underscore is legal — a static export puts its
+ * hashed assets under `_next/static/**` — and containment is enforced by the
+ * `..`, leading-slash and NUL checks below rather than by the first character.
+ */
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9_][a-zA-Z0-9_.\-/]*$/;
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+function validateCustomKey(key) {
+    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
+        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
+    }
+    if (key.includes('..')) {
+        return 'INVALID_KEY: path traversal (..) not allowed';
+    }
+    if (key.startsWith('/')) {
+        return 'INVALID_KEY: leading slash not allowed';
+    }
+    if (key.includes('\0')) {
+        return 'INVALID_KEY: null bytes not allowed';
+    }
+    if (!CUSTOM_KEY_REGEX.test(key)) {
+        return 'INVALID_KEY: must start with alphanumeric or underscore and contain only alphanumeric, dots, hyphens, underscores, and slashes';
+    }
+    return null;
+}

package/esm/custom-key.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+export declare function validateCustomKey(key: string): string | null;

package/esm/custom-key.js

@@ -0,0 +1,35 @@
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+const MAX_CUSTOM_KEY_LENGTH = 1024;
+/**
+ * The key alphabet. A leading underscore is legal — a static export puts its
+ * hashed assets under `_next/static/**` — and containment is enforced by the
+ * `..`, leading-slash and NUL checks below rather than by the first character.
+ */
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9_][a-zA-Z0-9_.\-/]*$/;
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+export function validateCustomKey(key) {
+    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
+        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
+    }
+    if (key.includes('..')) {
+        return 'INVALID_KEY: path traversal (..) not allowed';
+    }
+    if (key.startsWith('/')) {
+        return 'INVALID_KEY: leading slash not allowed';
+    }
+    if (key.includes('\0')) {
+        return 'INVALID_KEY: null bytes not allowed';
+    }
+    if (!CUSTOM_KEY_REGEX.test(key)) {
+        return 'INVALID_KEY: must start with alphanumeric or underscore and contain only alphanumeric, dots, hyphens, underscores, and slashes';
+    }
+    return null;
+}

package/esm/file-lifecycle.d.ts

@@ -0,0 +1,20 @@
+import type { StorageModuleConfig } from './types';
+/**
+ * The statuses in which a files row stands for bytes a reader can actually GET.
+ * A `requested` row is a claim, not an object — its presigned PUT may never have
+ * run — and `rejected`/`expired` are settled failures.
+ */
+export declare const LIVE_FILE_STATUSES: string[];
+/**
+ * The `status` column, when the module has one, for splicing into a select list.
+ */
+export declare function statusSelectFragment(storageConfig: StorageModuleConfig): string;
+/**
+ * Whether an existing row may be handed back as a dedup hit.
+ *
+ * Modules without the confirm-upload lifecycle have no `status` column, so there
+ * is nothing to read and every row is presumed live, as before.
+ */
+export declare function isLiveFileRow(storageConfig: StorageModuleConfig, row: {
+    status?: string;
+}): boolean;

package/esm/file-lifecycle.js

@@ -0,0 +1,23 @@
+/**
+ * The statuses in which a files row stands for bytes a reader can actually GET.
+ * A `requested` row is a claim, not an object — its presigned PUT may never have
+ * run — and `rejected`/`expired` are settled failures.
+ */
+export const LIVE_FILE_STATUSES = ['uploaded', 'processed'];
+/**
+ * The `status` column, when the module has one, for splicing into a select list.
+ */
+export function statusSelectFragment(storageConfig) {
+    return storageConfig.hasConfirmUpload ? ', status' : '';
+}
+/**
+ * Whether an existing row may be handed back as a dedup hit.
+ *
+ * Modules without the confirm-upload lifecycle have no `status` column, so there
+ * is nothing to read and every row is presumed live, as before.
+ */
+export function isLiveFileRow(storageConfig, row) {
+    if (!storageConfig.hasConfirmUpload)
+        return true;
+    return LIVE_FILE_STATUSES.includes(row.status);
+}

package/esm/index.d.ts

@@ -27,6 +27,7 @@
  * ```
  */
 export { CONFIRM_PREFIX_BYTES, confirmUploadedBytes, type ConfirmUploadInput, type ConfirmUploadVerdict, } from './confirm-upload';
+export { validateCustomKey } from './custom-key';
 export type { ResolvedBucketCoordinate } from './default-bucket';
 export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';

package/esm/index.js

@@ -27,6 +27,7 @@
  * ```
  */
 export { CONFIRM_PREFIX_BYTES, confirmUploadedBytes, } from './confirm-upload';
+export { validateCustomKey } from './custom-key';
 export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';

package/esm/managed-upload.js

@@ -19,6 +19,7 @@
  */
 import { Logger } from '@pgpmjs/logger';
 import { resolveDefaultBucket } from './default-bucket';
+import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { getFileRefFieldBinding } from './file-ref-registry';
 import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
@@ -192,7 +193,7 @@ export async function finalizeStagedUpload(args) {
     const finalKey = staged.contentHash;
     const existing = await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
         const result = await pgClient.query({
-            text: `SELECT id, key, mime_type, size, filename
+            text: `SELECT id, key, mime_type, size, filename${statusSelectFragment(storageConfig)}
              FROM ${storageConfig.filesQualifiedName}
              WHERE content_hash = $1 AND bucket_id = $2
              LIMIT 1`,
@@ -200,7 +201,22 @@ export async function finalizeStagedUpload(args) {
         });
         return result.rows[0];
     });
-    if (existing) {
+    // Only a row that already stands for stored bytes may absorb this upload. One
+    // that never received them is dropped, and the staged object is promoted as a
+    // fresh file below — which is also what keeps the insert possible, since the
+    // final key is the content hash and (bucket_id, key) is unique. The GC job the
+    // delete enqueues re-takes the reference count when it runs, by which point
+    // the replacement row exists, so it no-ops.
+    if (existing && !isLiveFileRow(storageConfig, existing)) {
+        log.info(`Restarting upload of hash ${staged.contentHash}: file ${existing.id} is ${existing.status}, so it carries no bytes`);
+        await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
+            await pgClient.query({
+                text: `DELETE FROM ${storageConfig.filesQualifiedName} WHERE id = $1`,
+                values: [existing.id],
+            });
+        });
+    }
+    else if (existing) {
         log.info(`Dedup hit: file ${existing.id} already carries hash ${staged.contentHash}`);
         await deleteS3Object(s3, staged.stagingKey);
         return {

package/esm/plugin.js

@@ -20,7 +20,9 @@ import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
 import { access, context as grafastContext, lambda, object } from 'grafast';
 import { checkTypeAgreement } from 'mime-bytes';
+import { validateCustomKey } from './custom-key';
 import { resolveDefaultBucket } from './default-bucket';
+import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { buildFileProjection } from './managed-upload';
 import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
@@ -30,9 +32,7 @@ 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_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 ---
 function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
@@ -40,24 +40,6 @@ function isValidSha256(hash) {
 function buildS3Key(contentHash) {
     return contentHash;
 }
-function validateCustomKey(key) {
-    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
-        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
-    }
-    if (key.includes('..')) {
-        return 'INVALID_KEY: path traversal (..) not allowed';
-    }
-    if (key.startsWith('/')) {
-        return 'INVALID_KEY: leading slash not allowed';
-    }
-    if (key.includes('\0')) {
-        return 'INVALID_KEY: null bytes not allowed';
-    }
-    if (!CUSTOM_KEY_REGEX.test(key)) {
-        return 'INVALID_KEY: must start with alphanumeric and contain only alphanumeric, dots, hyphens, underscores, and slashes';
-    }
-    return null;
-}
 function derivePathFromKey(key) {
     const lastSlash = key.lastIndexOf('/');
     if (lastSlash <= 0)
@@ -560,9 +542,20 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     }
     // Dedup / versioning check
     let previousVersionId = null;
+    // A row whose bytes never landed must not be reported as a dedup hit: the
+    // caller would store a reference to an object that is not in S3. Such a row is
+    // dropped instead, and the upload proceeds as a fresh one below — the insert is
+    // what enqueues the confirm-upload job, so restarting the lifecycle is the only
+    // way the retry can ever leave `requested`. Dropping it is also what keeps the
+    // retry insertable at all for a content-addressed key, where the key *is* the
+    // hash and a second row would collide on (bucket_id, key). The GC job the
+    // delete enqueues re-takes the reference count when it runs (≥5s later), by
+    // which point the replacement row exists, so it no-ops.
+    const statusColumn = statusSelectFragment(storageConfig);
+    let staleFileId = null;
     if (isCustomKey) {
         const existingResult = await txClient.query({
-            text: `SELECT id, content_hash
+            text: `SELECT id, content_hash${statusColumn}
        FROM ${storageConfig.filesQualifiedName}
        WHERE key = $1
          AND bucket_id = $2
@@ -573,24 +566,30 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         if (existingResult.rows.length > 0) {
             const existing = existingResult.rows[0];
             if (existing.content_hash === contentHash) {
-                log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
-                return {
-                    uploadUrl: null,
-                    fileId: existing.id,
-                    key: s3Key,
-                    deduplicated: true,
-                    expiresAt: null,
-                    previousVersionId: null,
-                    file: projectFile(existing.id, s3Key),
-                };
+                if (isLiveFileRow(storageConfig, existing)) {
+                    log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
+                    return {
+                        uploadUrl: null,
+                        fileId: existing.id,
+                        key: s3Key,
+                        deduplicated: true,
+                        expiresAt: null,
+                        previousVersionId: null,
+                        file: projectFile(existing.id, s3Key),
+                    };
+                }
+                staleFileId = existing.id;
+                log.info(`Restarting upload of key ${s3Key}: file ${staleFileId} is ${existing.status}, so it carries no bytes`);
+            }
+            else {
+                previousVersionId = existing.id;
+                log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
             }
-            previousVersionId = existing.id;
-            log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
         }
     }
     else {
         const dedupResult = await txClient.query({
-            text: `SELECT id
+            text: `SELECT id${statusColumn}
        FROM ${storageConfig.filesQualifiedName}
        WHERE content_hash = $1
          AND bucket_id = $2
@@ -599,18 +598,28 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         });
         if (dedupResult.rows.length > 0) {
             const existingFile = dedupResult.rows[0];
-            log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
-            return {
-                uploadUrl: null,
-                fileId: existingFile.id,
-                key: s3Key,
-                deduplicated: true,
-                expiresAt: null,
-                previousVersionId: null,
-                file: projectFile(existingFile.id, s3Key),
-            };
+            if (isLiveFileRow(storageConfig, existingFile)) {
+                log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
+                return {
+                    uploadUrl: null,
+                    fileId: existingFile.id,
+                    key: s3Key,
+                    deduplicated: true,
+                    expiresAt: null,
+                    previousVersionId: null,
+                    file: projectFile(existingFile.id, s3Key),
+                };
+            }
+            staleFileId = existingFile.id;
+            log.info(`Restarting upload of hash ${contentHash}: file ${staleFileId} is ${existingFile.status}, so it carries no bytes`);
         }
     }
+    if (staleFileId !== null) {
+        await txClient.query({
+            text: `DELETE FROM ${storageConfig.filesQualifiedName} WHERE id = $1`,
+            values: [staleFileId],
+        });
+    }
     // Auto-derive ltree path from custom key directory (only when has_path_shares)
     const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
     // Create file record

package/esm/storage-module-cache.js

@@ -56,6 +56,7 @@ const APP_STORAGE_MODULE_QUERY = `
     sm.max_bulk_files,
     sm.max_bulk_total_size,
     sm.has_path_shares,
+    sm.has_confirm_upload,
     NULL AS entity_schema,
     NULL AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -94,6 +95,7 @@ const ALL_STORAGE_MODULES_QUERY = `
     sm.max_bulk_files,
     sm.max_bulk_total_size,
     sm.has_path_shares,
+    sm.has_confirm_upload,
     es.schema_name AS entity_schema,
     et.name AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -132,6 +134,7 @@ function buildConfig(row) {
         maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
         cacheTtlSeconds,
         hasPathShares: row.has_path_shares ?? false,
+        hasConfirmUpload: row.has_confirm_upload ?? false,
         maxBulkFiles: row.max_bulk_files ?? DEFAULT_MAX_BULK_FILES,
         maxBulkTotalSize: row.max_bulk_total_size ?? DEFAULT_MAX_BULK_TOTAL_SIZE,
     };

package/esm/types.d.ts

@@ -61,6 +61,12 @@ export interface StorageModuleConfig {
     cacheTtlSeconds: number;
     /** Whether this storage module uses ltree path + path shares (determines if path column exists on files) */
     hasPathShares: boolean;
+    /**
+     * Whether the files table carries the confirm-upload lifecycle (`status`,
+     * `promoted_at`). Only then can a row be told apart from the bytes it claims:
+     * without it every row is treated as live, because there is nothing to read.
+     */
+    hasConfirmUpload: boolean;
     /** Max files per requestBulkUploadUrls batch (default: 100) */
     maxBulkFiles: number;
     /** Max total size per bulk upload batch in bytes (default: 1GB) */

package/file-lifecycle.d.ts

@@ -0,0 +1,20 @@
+import type { StorageModuleConfig } from './types';
+/**
+ * The statuses in which a files row stands for bytes a reader can actually GET.
+ * A `requested` row is a claim, not an object — its presigned PUT may never have
+ * run — and `rejected`/`expired` are settled failures.
+ */
+export declare const LIVE_FILE_STATUSES: string[];
+/**
+ * The `status` column, when the module has one, for splicing into a select list.
+ */
+export declare function statusSelectFragment(storageConfig: StorageModuleConfig): string;
+/**
+ * Whether an existing row may be handed back as a dedup hit.
+ *
+ * Modules without the confirm-upload lifecycle have no `status` column, so there
+ * is nothing to read and every row is presumed live, as before.
+ */
+export declare function isLiveFileRow(storageConfig: StorageModuleConfig, row: {
+    status?: string;
+}): boolean;

package/file-lifecycle.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIVE_FILE_STATUSES = void 0;
+exports.statusSelectFragment = statusSelectFragment;
+exports.isLiveFileRow = isLiveFileRow;
+/**
+ * The statuses in which a files row stands for bytes a reader can actually GET.
+ * A `requested` row is a claim, not an object — its presigned PUT may never have
+ * run — and `rejected`/`expired` are settled failures.
+ */
+exports.LIVE_FILE_STATUSES = ['uploaded', 'processed'];
+/**
+ * The `status` column, when the module has one, for splicing into a select list.
+ */
+function statusSelectFragment(storageConfig) {
+    return storageConfig.hasConfirmUpload ? ', status' : '';
+}
+/**
+ * Whether an existing row may be handed back as a dedup hit.
+ *
+ * Modules without the confirm-upload lifecycle have no `status` column, so there
+ * is nothing to read and every row is presumed live, as before.
+ */
+function isLiveFileRow(storageConfig, row) {
+    if (!storageConfig.hasConfirmUpload)
+        return true;
+    return exports.LIVE_FILE_STATUSES.includes(row.status);
+}

package/index.d.ts

@@ -27,6 +27,7 @@
  * ```
  */
 export { CONFIRM_PREFIX_BYTES, confirmUploadedBytes, type ConfirmUploadInput, type ConfirmUploadVerdict, } from './confirm-upload';
+export { validateCustomKey } from './custom-key';
 export type { ResolvedBucketCoordinate } from './default-bucket';
 export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';

package/index.js

@@ -28,10 +28,12 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getStorageModuleConfigForOwner = exports.getStorageModuleConfig = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.resolveS3ForDatabase = exports.resolveS3 = exports.provisionAndRecordPhysicalBucket = exports.mintPhysicalBucketName = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
+exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getStorageModuleConfigForOwner = exports.getStorageModuleConfig = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.resolveS3ForDatabase = exports.resolveS3 = exports.provisionAndRecordPhysicalBucket = exports.mintPhysicalBucketName = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.validateCustomKey = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
 var confirm_upload_1 = require("./confirm-upload");
 Object.defineProperty(exports, "CONFIRM_PREFIX_BYTES", { enumerable: true, get: function () { return confirm_upload_1.CONFIRM_PREFIX_BYTES; } });
 Object.defineProperty(exports, "confirmUploadedBytes", { enumerable: true, get: function () { return confirm_upload_1.confirmUploadedBytes; } });
+var custom_key_1 = require("./custom-key");
+Object.defineProperty(exports, "validateCustomKey", { enumerable: true, get: function () { return custom_key_1.validateCustomKey; } });
 var default_bucket_1 = require("./default-bucket");
 Object.defineProperty(exports, "resolveDefaultBucket", { enumerable: true, get: function () { return default_bucket_1.resolveDefaultBucket; } });
 var download_url_field_1 = require("./download-url-field");

package/managed-upload.js

@@ -25,6 +25,7 @@ exports.assertUploadAllowedByBucket = assertUploadAllowedByBucket;
 exports.finalizeStagedUpload = finalizeStagedUpload;
 const logger_1 = require("@pgpmjs/logger");
 const default_bucket_1 = require("./default-bucket");
+const file_lifecycle_1 = require("./file-lifecycle");
 const file_ref_registry_1 = require("./file-ref-registry");
 const physical_bucket_1 = require("./physical-bucket");
 const request_pg_client_1 = require("./request-pg-client");
@@ -198,7 +199,7 @@ async function finalizeStagedUpload(args) {
     const finalKey = staged.contentHash;
     const existing = await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, async (pgClient) => {
         const result = await pgClient.query({
-            text: `SELECT id, key, mime_type, size, filename
+            text: `SELECT id, key, mime_type, size, filename${(0, file_lifecycle_1.statusSelectFragment)(storageConfig)}
              FROM ${storageConfig.filesQualifiedName}
              WHERE content_hash = $1 AND bucket_id = $2
              LIMIT 1`,
@@ -206,7 +207,22 @@ async function finalizeStagedUpload(args) {
         });
         return result.rows[0];
     });
-    if (existing) {
+    // Only a row that already stands for stored bytes may absorb this upload. One
+    // that never received them is dropped, and the staged object is promoted as a
+    // fresh file below — which is also what keeps the insert possible, since the
+    // final key is the content hash and (bucket_id, key) is unique. The GC job the
+    // delete enqueues re-takes the reference count when it runs, by which point
+    // the replacement row exists, so it no-ops.
+    if (existing && !(0, file_lifecycle_1.isLiveFileRow)(storageConfig, existing)) {
+        log.info(`Restarting upload of hash ${staged.contentHash}: file ${existing.id} is ${existing.status}, so it carries no bytes`);
+        await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, async (pgClient) => {
+            await pgClient.query({
+                text: `DELETE FROM ${storageConfig.filesQualifiedName} WHERE id = $1`,
+                values: [existing.id],
+            });
+        });
+    }
+    else if (existing) {
         log.info(`Dedup hit: file ${existing.id} already carries hash ${staged.contentHash}`);
         await (0, s3_signer_1.deleteS3Object)(s3, staged.stagingKey);
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.13.1",
+  "version": "1.14.1",
   "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl mutation and downloadUrl computed field",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -42,10 +42,10 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1052.0",
     "@aws-sdk/s3-request-presigner": "^3.1052.0",
-    "@pgpmjs/logger": "^2.24.1",
+    "@pgpmjs/logger": "^2.25.0",
     "@pgsql/quotes": "^18.2.4",
     "lru-cache": "^11.2.7",
-    "mime-bytes": "^0.31.0"
+    "mime-bytes": "^0.32.0"
   },
   "peerDependencies": {
     "grafast": "^1.1.1",
@@ -57,9 +57,9 @@
     "postgraphile": "^5.1.3"
   },
   "devDependencies": {
-    "@constructive-io/s3-utils": "^2.31.0",
+    "@constructive-io/s3-utils": "^2.32.0",
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "10ee73e43c2277405c0e19423e2075baef6c2755"
+  "gitHead": "8d77dfe57bb328cbdfe10732b10ca24865adf9c0"
 }

package/plugin.js

@@ -24,7 +24,9 @@ require("graphile-build");
 const logger_1 = require("@pgpmjs/logger");
 const grafast_1 = require("grafast");
 const mime_bytes_1 = require("mime-bytes");
+const custom_key_1 = require("./custom-key");
 const default_bucket_1 = require("./default-bucket");
+const file_lifecycle_1 = require("./file-lifecycle");
 const managed_upload_1 = require("./managed-upload");
 const physical_bucket_1 = require("./physical-bucket");
 const request_pg_client_1 = require("./request-pg-client");
@@ -34,9 +36,7 @@ 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_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 ---
 function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
@@ -44,24 +44,6 @@ function isValidSha256(hash) {
 function buildS3Key(contentHash) {
     return contentHash;
 }
-function validateCustomKey(key) {
-    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
-        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
-    }
-    if (key.includes('..')) {
-        return 'INVALID_KEY: path traversal (..) not allowed';
-    }
-    if (key.startsWith('/')) {
-        return 'INVALID_KEY: leading slash not allowed';
-    }
-    if (key.includes('\0')) {
-        return 'INVALID_KEY: null bytes not allowed';
-    }
-    if (!CUSTOM_KEY_REGEX.test(key)) {
-        return 'INVALID_KEY: must start with alphanumeric and contain only alphanumeric, dots, hyphens, underscores, and slashes';
-    }
-    return null;
-}
 function derivePathFromKey(key) {
     const lastSlash = key.lastIndexOf('/');
     if (lastSlash <= 0)
@@ -552,7 +534,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         if (!bucket.allow_custom_keys) {
             throw new Error('CUSTOM_KEY_NOT_ALLOWED: bucket does not allow custom keys');
         }
-        const keyError = validateCustomKey(customKey);
+        const keyError = (0, custom_key_1.validateCustomKey)(customKey);
         if (keyError) {
             throw new Error(keyError);
         }
@@ -564,9 +546,20 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     }
     // Dedup / versioning check
     let previousVersionId = null;
+    // A row whose bytes never landed must not be reported as a dedup hit: the
+    // caller would store a reference to an object that is not in S3. Such a row is
+    // dropped instead, and the upload proceeds as a fresh one below — the insert is
+    // what enqueues the confirm-upload job, so restarting the lifecycle is the only
+    // way the retry can ever leave `requested`. Dropping it is also what keeps the
+    // retry insertable at all for a content-addressed key, where the key *is* the
+    // hash and a second row would collide on (bucket_id, key). The GC job the
+    // delete enqueues re-takes the reference count when it runs (≥5s later), by
+    // which point the replacement row exists, so it no-ops.
+    const statusColumn = (0, file_lifecycle_1.statusSelectFragment)(storageConfig);
+    let staleFileId = null;
     if (isCustomKey) {
         const existingResult = await txClient.query({
-            text: `SELECT id, content_hash
+            text: `SELECT id, content_hash${statusColumn}
        FROM ${storageConfig.filesQualifiedName}
        WHERE key = $1
          AND bucket_id = $2
@@ -577,24 +570,30 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         if (existingResult.rows.length > 0) {
             const existing = existingResult.rows[0];
             if (existing.content_hash === contentHash) {
-                log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
-                return {
-                    uploadUrl: null,
-                    fileId: existing.id,
-                    key: s3Key,
-                    deduplicated: true,
-                    expiresAt: null,
-                    previousVersionId: null,
-                    file: projectFile(existing.id, s3Key),
-                };
+                if ((0, file_lifecycle_1.isLiveFileRow)(storageConfig, existing)) {
+                    log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
+                    return {
+                        uploadUrl: null,
+                        fileId: existing.id,
+                        key: s3Key,
+                        deduplicated: true,
+                        expiresAt: null,
+                        previousVersionId: null,
+                        file: projectFile(existing.id, s3Key),
+                    };
+                }
+                staleFileId = existing.id;
+                log.info(`Restarting upload of key ${s3Key}: file ${staleFileId} is ${existing.status}, so it carries no bytes`);
+            }
+            else {
+                previousVersionId = existing.id;
+                log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
             }
-            previousVersionId = existing.id;
-            log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
         }
     }
     else {
         const dedupResult = await txClient.query({
-            text: `SELECT id
+            text: `SELECT id${statusColumn}
        FROM ${storageConfig.filesQualifiedName}
        WHERE content_hash = $1
          AND bucket_id = $2
@@ -603,18 +602,28 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         });
         if (dedupResult.rows.length > 0) {
             const existingFile = dedupResult.rows[0];
-            log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
-            return {
-                uploadUrl: null,
-                fileId: existingFile.id,
-                key: s3Key,
-                deduplicated: true,
-                expiresAt: null,
-                previousVersionId: null,
-                file: projectFile(existingFile.id, s3Key),
-            };
+            if ((0, file_lifecycle_1.isLiveFileRow)(storageConfig, existingFile)) {
+                log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
+                return {
+                    uploadUrl: null,
+                    fileId: existingFile.id,
+                    key: s3Key,
+                    deduplicated: true,
+                    expiresAt: null,
+                    previousVersionId: null,
+                    file: projectFile(existingFile.id, s3Key),
+                };
+            }
+            staleFileId = existingFile.id;
+            log.info(`Restarting upload of hash ${contentHash}: file ${staleFileId} is ${existingFile.status}, so it carries no bytes`);
         }
     }
+    if (staleFileId !== null) {
+        await txClient.query({
+            text: `DELETE FROM ${storageConfig.filesQualifiedName} WHERE id = $1`,
+            values: [staleFileId],
+        });
+    }
     // Auto-derive ltree path from custom key directory (only when has_path_shares)
     const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
     // Create file record

package/storage-module-cache.js

@@ -69,6 +69,7 @@ const APP_STORAGE_MODULE_QUERY = `
     sm.max_bulk_files,
     sm.max_bulk_total_size,
     sm.has_path_shares,
+    sm.has_confirm_upload,
     NULL AS entity_schema,
     NULL AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -107,6 +108,7 @@ const ALL_STORAGE_MODULES_QUERY = `
     sm.max_bulk_files,
     sm.max_bulk_total_size,
     sm.has_path_shares,
+    sm.has_confirm_upload,
     es.schema_name AS entity_schema,
     et.name AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -145,6 +147,7 @@ function buildConfig(row) {
         maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
         cacheTtlSeconds,
         hasPathShares: row.has_path_shares ?? false,
+        hasConfirmUpload: row.has_confirm_upload ?? false,
         maxBulkFiles: row.max_bulk_files ?? DEFAULT_MAX_BULK_FILES,
         maxBulkTotalSize: row.max_bulk_total_size ?? DEFAULT_MAX_BULK_TOTAL_SIZE,
     };

package/types.d.ts

@@ -61,6 +61,12 @@ export interface StorageModuleConfig {
     cacheTtlSeconds: number;
     /** Whether this storage module uses ltree path + path shares (determines if path column exists on files) */
     hasPathShares: boolean;
+    /**
+     * Whether the files table carries the confirm-upload lifecycle (`status`,
+     * `promoted_at`). Only then can a row be told apart from the bytes it claims:
+     * without it every row is treated as live, because there is nothing to read.
+     */
+    hasConfirmUpload: boolean;
     /** Max files per requestBulkUploadUrls batch (default: 100) */
     maxBulkFiles: number;
     /** Max total size per bulk upload batch in bytes (default: 1GB) */