graphile-presigned-url-plugin 1.11.4 → 1.13.0

package/plugin.js

@@ -23,6 +23,10 @@ exports.createPresignedUrlPlugin = createPresignedUrlPlugin;
 require("graphile-build");
 const logger_1 = require("@pgpmjs/logger");
 const grafast_1 = require("grafast");
+const mime_bytes_1 = require("mime-bytes");
+const default_bucket_1 = require("./default-bucket");
+const managed_upload_1 = require("./managed-upload");
+const physical_bucket_1 = require("./physical-bucket");
 const request_pg_client_1 = require("./request-pg-client");
 const s3_signer_1 = require("./s3-signer");
 const storage_module_cache_1 = require("./storage-module-cache");
@@ -71,87 +75,20 @@ async function resolveDatabaseId(pgClient) {
     });
     return result.rows[0]?.id ?? null;
 }
-function resolveS3(options) {
-    if (typeof options.s3 === 'function') {
-        const resolved = options.s3();
-        options.s3 = resolved;
-        return resolved;
-    }
-    return options.s3;
-}
-/**
- * Mint the physical S3 bucket name for a logical bucket's first provision.
- *
- * This is a naming *policy*, consulted exactly once per bucket — before the
- * physical bucket exists. Once provisioned, the recorded `physical_name` on
- * the row is authoritative and this function must not be consulted again.
- */
-function mintPhysicalBucketName(options, databaseId, bucketKey) {
-    if (options.resolveBucketName) {
-        return options.resolveBucketName(databaseId, bucketKey);
-    }
-    // Single-bucket deployment: the globally configured bucket is the physical bucket.
-    return resolveS3(options).bucket;
-}
-/**
- * Build the S3 config for a *known* physical bucket. `physicalName` is
- * required — callers must resolve the coordinate (stored row value, or a
- * freshly provisioned name) before getting here. No name is ever recomputed.
- */
-function resolveS3ForDatabase(options, storageConfig, physicalName) {
-    const globalS3 = resolveS3(options);
-    const publicUrlPrefix = storageConfig.publicUrlPrefix != null
-        ? storageConfig.publicUrlPrefix
-        : globalS3.publicUrlPrefix;
-    if (physicalName === globalS3.bucket && publicUrlPrefix === globalS3.publicUrlPrefix) {
-        return globalS3;
-    }
-    return {
-        ...globalS3,
-        bucket: physicalName,
-        ...(publicUrlPrefix != null ? { publicUrlPrefix } : {}),
-    };
-}
 /**
- * First provision of a logical bucket: mint a name, create the physical S3
- * bucket, and record the exact name on the source row. Returns the recorded
- * physical name.
- *
- * Only called when the row has no `physical_name` yet. Afterwards the stored
- * value is the durable coordinate: route resolution and every later read use
- * it verbatim; nothing is recomputed.
+ * Resolve the bucket an upload mutation writes into.
  *
- * The record write runs in the system lane (privileged role, so it bypasses the
- * RLS that stops request roles from UPDATE-ing bucket rows) — it is server
- * bookkeeping, not request data. It still carries the tenant `database_id`
- * claim, because the buckets table's catalog-sync trigger calls
- * `jwt_private.current_database_id()` and would otherwise raise
- * DATABASE_CLAIM_REQUIRED; `withRequestPgClient` applies that claim inside the
- * write's transaction without switching off the privileged role.
- * `bucket` (the cached config) is mutated in place so subsequent reads observe
- * the recorded name without a DB round-trip.
+ * A named `bucketKey` is the caller's override and is read directly, as before.
+ * An omitted one asks the database for the tenant's reserved default tag for the
+ * requested access, so a missing or ambiguous default raises in SQL rather than
+ * falling back to a server-global bucket name here.
  */
-async function provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, allowedOrigins) {
-    const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
-    if (options.ensureBucketProvisioned && !(0, storage_module_cache_1.isS3BucketProvisioned)(s3BucketName)) {
-        log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
-        await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
-        (0, storage_module_cache_1.markS3BucketProvisioned)(s3BucketName);
-        log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
+async function resolveUploadBucket(pgClient, storageConfig, databaseId, bucketKey, ownerId, isPublic) {
+    if (bucketKey) {
+        return (0, storage_module_cache_1.getBucketConfig)(pgClient, storageConfig, databaseId, bucketKey, ownerId || undefined);
     }
-    // Record the physical coordinate on the source row. The `physical_name IS NULL`
-    // guard keeps this idempotent and race-safe across concurrent first uploads.
-    // The catalog-sync trigger on this UPDATE needs `jwt.claims.database_id`, so the
-    // write runs under the resolved database claim (privileged role preserved).
-    await (0, request_pg_client_1.withRequestPgClient)(withPgClient, { 'jwt.claims.database_id': databaseId }, (client) => client.query({
-        text: `UPDATE ${storageConfig.bucketsQualifiedName}
-             SET physical_name = $1
-             WHERE id = $2 AND physical_name IS NULL`,
-        values: [s3BucketName, bucket.id],
-    }));
-    bucket.physical_name = s3BucketName;
-    log.info(`Recorded physical_name="${s3BucketName}" on bucket ${bucket.id}`);
-    return s3BucketName;
+    const coordinate = await (0, default_bucket_1.resolveDefaultBucket)(pgClient, databaseId, storageConfig.scope, ownerId, isPublic, null);
+    return (0, storage_module_cache_1.getBucketConfig)(pgClient, storageConfig, databaseId, coordinate.resolvedKey, ownerId || undefined);
 }
 // --- Plugin factory ---
 function createPresignedUrlPlugin(options) {
@@ -170,6 +107,14 @@ function createPresignedUrlPlugin(options) {
                     if (!isRootMutation)
                         return fields;
                     const { graphql: { GraphQLString, GraphQLNonNull, GraphQLInt, GraphQLBoolean, GraphQLObjectType, GraphQLInputObjectType, GraphQLList, }, } = build;
+                    // The projection document is jsonb-shaped. PostGraphile registers a JSON
+                    // scalar whenever the schema has a jsonb column, which any storage-equipped
+                    // database does; if it is absent the payload simply omits the field rather
+                    // than failing schema build over a field nothing can have asked for yet.
+                    const jsonType = build.getTypeByName('JSON') ?? null;
+                    if (!jsonType) {
+                        log.warn('No JSON scalar in this schema; upload payloads will omit the `file` projection');
+                    }
                     const bucketCodecs = Object.values(build.input.pgRegistry.pgCodecs).filter((codec) => codec.attributes && codec.extensions?.tags?.storageBuckets);
                     if (bucketCodecs.length === 0)
                         return fields;
@@ -203,7 +148,8 @@ function createPresignedUrlPlugin(options) {
                         const InputType = new GraphQLInputObjectType({
                             name: `Upload${filesTypeName}Input`,
                             fields: {
-                                bucketKey: { type: new GraphQLNonNull(GraphQLString), description: 'Bucket key (e.g., "public", "private")' },
+                                bucketKey: { type: GraphQLString, description: 'Bucket key (e.g., "public", "private"). Omit to use the database\'s default bucket for the requested access.' },
+                                isPublic: { type: GraphQLBoolean, description: 'Which default bucket to resolve when bucketKey is omitted: the public one (true) or the private one (default false). Ignored when bucketKey is given.' },
                                 ...(hasOwnerId
                                     ? { ownerId: { type: new GraphQLNonNull(ownerIdGqlType || GraphQLString), description: 'Owner entity ID (required for entity-scoped buckets)' } }
                                     : {}),
@@ -223,6 +169,16 @@ function createPresignedUrlPlugin(options) {
                                 deduplicated: { type: new GraphQLNonNull(GraphQLBoolean), description: 'Whether this file was deduplicated (content already exists)' },
                                 expiresAt: { type: GraphQLString, description: 'Presigned URL expiry time (null if deduplicated)' },
                                 previousVersionId: { type: GraphQLString, description: 'ID of the previous version (when using custom keys)' },
+                                ...(jsonType
+                                    ? {
+                                        file: {
+                                            type: jsonType,
+                                            description: 'The projection document for the created file: {id, key, bucket_id, mime, size, filename, url?}. ' +
+                                                'Store this verbatim in an image/upload column — its `id` is what keeps the object from being ' +
+                                                'garbage collected while the column still references it.',
+                                        },
+                                    }
+                                    : {}),
                             },
                         });
                         const capturedFilesCodec = filesCodec;
@@ -236,6 +192,7 @@ function createPresignedUrlPlugin(options) {
                             plan(_$mutation, fieldArgs) {
                                 const $input = fieldArgs.getRaw('input');
                                 const $bucketKey = (0, grafast_1.access)($input, 'bucketKey');
+                                const $isPublic = (0, grafast_1.access)($input, 'isPublic');
                                 const $contentHash = (0, grafast_1.access)($input, 'contentHash');
                                 const $contentType = (0, grafast_1.access)($input, 'contentType');
                                 const $size = (0, grafast_1.access)($input, 'size');
@@ -246,6 +203,7 @@ function createPresignedUrlPlugin(options) {
                                 const $pgSettings = (0, grafast_1.context)().get('pgSettings');
                                 const $combined = (0, grafast_1.object)({
                                     bucketKey: $bucketKey,
+                                    isPublic: $isPublic,
                                     ownerId: $ownerId,
                                     contentHash: $contentHash,
                                     contentType: $contentType,
@@ -268,16 +226,16 @@ function createPresignedUrlPlugin(options) {
                                     const storageConfig = (0, storage_module_cache_1.resolveStorageConfigFromCodec)(capturedFilesCodec, allConfigs);
                                     if (!storageConfig)
                                         throw new Error('STORAGE_MODULE_NOT_FOUND');
-                                    // Bucket config read under the request role (RLS-gated visibility).
-                                    const bucket = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => (0, storage_module_cache_1.getBucketConfig)(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    // Bucket resolution + read under the request role (RLS-gated visibility).
+                                    const bucket = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => resolveUploadBucket(pgClient, storageConfig, databaseId, vals.bucketKey ?? null, vals.ownerId ?? null, vals.isPublic === true));
                                     if (!bucket)
                                         throw new Error('BUCKET_NOT_FOUND');
                                     // First provision mints + records the coordinate; afterwards the
                                     // stored physical_name is authoritative and nothing is recomputed.
                                     const physicalName = bucket.physical_name === null
-                                        ? await provisionAndRecordPhysicalBucket(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+                                        ? await (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
                                         : bucket.physical_name;
-                                    const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
+                                    const s3ForDb = (0, physical_bucket_1.resolveS3ForDatabase)(options, storageConfig, physicalName);
                                     // File row INSERT under the request role (RLS enforced).
                                     return (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (txClient) => processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
                                         contentHash: vals.contentHash,
@@ -309,12 +267,14 @@ function createPresignedUrlPlugin(options) {
                                 deduplicated: { type: new GraphQLNonNull(GraphQLBoolean) },
                                 expiresAt: { type: GraphQLString },
                                 previousVersionId: { type: GraphQLString },
+                                ...(jsonType ? { file: { type: jsonType, description: 'The projection document for the created file.' } } : {}),
                             },
                         });
                         const BulkInputType = new GraphQLInputObjectType({
                             name: `Upload${filesTypeName}BulkInput`,
                             fields: {
-                                bucketKey: { type: new GraphQLNonNull(GraphQLString), description: 'Bucket key (e.g., "public", "private")' },
+                                bucketKey: { type: GraphQLString, description: 'Bucket key (e.g., "public", "private"). Omit to use the database\'s default bucket for the requested access.' },
+                                isPublic: { type: GraphQLBoolean, description: 'Which default bucket to resolve when bucketKey is omitted. Ignored when bucketKey is given.' },
                                 ...(hasOwnerId
                                     ? { ownerId: { type: new GraphQLNonNull(ownerIdGqlType || GraphQLString), description: 'Owner entity ID (required for entity-scoped buckets)' } }
                                     : {}),
@@ -338,12 +298,14 @@ function createPresignedUrlPlugin(options) {
                             plan(_$mutation, fieldArgs) {
                                 const $input = fieldArgs.getRaw('input');
                                 const $bucketKey = (0, grafast_1.access)($input, 'bucketKey');
+                                const $isPublic = (0, grafast_1.access)($input, 'isPublic');
                                 const $ownerId = hasOwnerId ? (0, grafast_1.access)($input, 'ownerId') : (0, grafast_1.lambda)(null, () => null);
                                 const $files = (0, grafast_1.access)($input, 'files');
                                 const $withPgClient = (0, grafast_1.context)().get('withPgClient');
                                 const $pgSettings = (0, grafast_1.context)().get('pgSettings');
                                 const $combined = (0, grafast_1.object)({
                                     bucketKey: $bucketKey,
+                                    isPublic: $isPublic,
                                     ownerId: $ownerId,
                                     files: $files,
                                     withPgClient: $withPgClient,
@@ -362,8 +324,8 @@ function createPresignedUrlPlugin(options) {
                                     const storageConfig = (0, storage_module_cache_1.resolveStorageConfigFromCodec)(capturedFilesCodec, allConfigs);
                                     if (!storageConfig)
                                         throw new Error('STORAGE_MODULE_NOT_FOUND');
-                                    // Bucket config read under the request role (RLS-gated visibility).
-                                    const bucket = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => (0, storage_module_cache_1.getBucketConfig)(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    // Bucket resolution + read under the request role (RLS-gated visibility).
+                                    const bucket = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => resolveUploadBucket(pgClient, storageConfig, databaseId, vals.bucketKey ?? null, vals.ownerId ?? null, vals.isPublic === true));
                                     if (!bucket)
                                         throw new Error('BUCKET_NOT_FOUND');
                                     // Enforce bulk upload limits
@@ -378,9 +340,9 @@ function createPresignedUrlPlugin(options) {
                                     // First provision mints + records the coordinate; afterwards the
                                     // stored physical_name is authoritative and nothing is recomputed.
                                     const physicalName = bucket.physical_name === null
-                                        ? await provisionAndRecordPhysicalBucket(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+                                        ? await (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
                                         : bucket.physical_name;
-                                    const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
+                                    const s3ForDb = (0, physical_bucket_1.resolveS3ForDatabase)(options, storageConfig, physicalName);
                                     // File row INSERTs under the request role (RLS enforced).
                                     return (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, async (txClient) => {
                                         const results = [];
@@ -509,7 +471,7 @@ function createPresignedUrlPlugin(options) {
                                                     log.warn(`Bucket ${fileRow.bucket_id} has no physical_name; skipping S3 delete`);
                                                     return;
                                                 }
-                                                const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
+                                                const s3ForDb = (0, physical_bucket_1.resolveS3ForDatabase)(options, storageConfig, physicalName);
                                                 await (0, s3_signer_1.deleteS3Object)(s3ForDb, fileRow.key);
                                                 log.info(`Sync S3 delete succeeded for key=${fileRow.key}`);
                                             });
@@ -548,6 +510,16 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
             throw new Error('INVALID_FILENAME');
         }
     }
+    // The bytes are not here to be examined — the client PUTs them straight to S3 —
+    // so this checks the two claims that *are* here against each other. It is the
+    // cheap half of the rule: an upload declaring `image/jpeg` under the name
+    // `payload.html` is refused before a row exists, without reading a byte. The
+    // bytes themselves are checked on confirmation, before the row leaves
+    // `requested`.
+    const agreement = (0, mime_bytes_1.checkTypeAgreement)({ filename, declaredMime: contentType });
+    if (!agreement.ok) {
+        throw new Error(`UPLOAD_TYPE_MISMATCH: ${agreement.violation.message}`);
+    }
     // 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;
@@ -568,6 +540,11 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     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`);
     }
+    // The projection document the caller stores in an image/upload column. Built
+    // from the same values the files row carries, so the column and the row cannot
+    // disagree, and it names the files row by id — which is what stops GC from
+    // collecting an object a document still points at.
+    const projectFile = (fileId, key) => (0, managed_upload_1.buildFileProjection)({ id: fileId, key, bucketId: bucket.id, mime: contentType, size, filename }, bucket, s3ForDb);
     // Determine S3 key
     let s3Key;
     let isCustomKey = false;
@@ -608,6 +585,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
                     deduplicated: true,
                     expiresAt: null,
                     previousVersionId: null,
+                    file: projectFile(existing.id, s3Key),
                 };
             }
             previousVersionId = existing.id;
@@ -633,6 +611,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
                 deduplicated: true,
                 expiresAt: null,
                 previousVersionId: null,
+                file: projectFile(existingFile.id, s3Key),
             };
         }
     }
@@ -673,6 +652,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         deduplicated: false,
         expiresAt,
         previousVersionId,
+        file: projectFile(fileId, s3Key),
     };
 }
 exports.PresignedUrlPlugin = createPresignedUrlPlugin;

package/s3-signer.d.ts

@@ -36,6 +36,35 @@ export declare function generatePresignedGetUrl(s3Config: S3Config, key: string,
  * @param key - S3 object key to delete
  */
 export declare function deleteS3Object(s3Config: S3Config, key: string): Promise<void>;
+/**
+ * Copy an object within the same physical bucket, preserving its content type.
+ *
+ * Used to promote a staged upload to its content-addressed key: the bytes are
+ * hashed as they stream in, so the final key is only known once the stream ends.
+ * Server-side copy keeps that promotion off the application's wire.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param sourceKey - The staged key the bytes were written to
+ * @param destinationKey - The final key (the content hash)
+ * @param contentType - MIME type to record on the destination object
+ */
+export declare function copyS3Object(s3Config: S3Config, sourceKey: string, destinationKey: string, contentType: string): Promise<void>;
+/**
+ * Read the leading bytes of an object.
+ *
+ * A ranged GET, because the only reason to touch bytes the client uploaded
+ * directly is to see what they actually are: a magic-byte signature lives in the
+ * first few dozen bytes, so validating a 2GB video costs the same as validating
+ * an icon.
+ *
+ * Returns null when the object is not there — the presigned lane's ordinary
+ * "client never PUT it" case, which is an expiry rather than a failure.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key
+ * @param byteCount - How many leading bytes to read
+ */
+export declare function readObjectPrefix(s3Config: S3Config, key: string, byteCount: number): Promise<Buffer | null>;
 /**
  * Check if an object exists in S3 and optionally verify its content-type.
  *

package/s3-signer.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generatePresignedPutUrl = generatePresignedPutUrl;
 exports.generatePresignedGetUrl = generatePresignedGetUrl;
 exports.deleteS3Object = deleteS3Object;
+exports.copyS3Object = copyS3Object;
+exports.readObjectPrefix = readObjectPrefix;
 exports.headObject = headObject;
 const client_s3_1 = require("@aws-sdk/client-s3");
 const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
@@ -74,6 +76,66 @@ async function deleteS3Object(s3Config, key) {
     }));
     log.debug(`Deleted S3 object: bucket=${s3Config.bucket}, key=${key}`);
 }
+/**
+ * Copy an object within the same physical bucket, preserving its content type.
+ *
+ * Used to promote a staged upload to its content-addressed key: the bytes are
+ * hashed as they stream in, so the final key is only known once the stream ends.
+ * Server-side copy keeps that promotion off the application's wire.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param sourceKey - The staged key the bytes were written to
+ * @param destinationKey - The final key (the content hash)
+ * @param contentType - MIME type to record on the destination object
+ */
+async function copyS3Object(s3Config, sourceKey, destinationKey, contentType) {
+    await s3Config.client.send(new client_s3_1.CopyObjectCommand({
+        Bucket: s3Config.bucket,
+        Key: destinationKey,
+        CopySource: `${s3Config.bucket}/${sourceKey}`,
+        ContentType: contentType,
+        MetadataDirective: 'REPLACE',
+    }));
+    log.debug(`Copied S3 object: bucket=${s3Config.bucket}, ${sourceKey} → ${destinationKey}`);
+}
+/**
+ * Read the leading bytes of an object.
+ *
+ * A ranged GET, because the only reason to touch bytes the client uploaded
+ * directly is to see what they actually are: a magic-byte signature lives in the
+ * first few dozen bytes, so validating a 2GB video costs the same as validating
+ * an icon.
+ *
+ * Returns null when the object is not there — the presigned lane's ordinary
+ * "client never PUT it" case, which is an expiry rather than a failure.
+ *
+ * @param s3Config - S3 client and bucket configuration
+ * @param key - S3 object key
+ * @param byteCount - How many leading bytes to read
+ */
+async function readObjectPrefix(s3Config, key, byteCount) {
+    try {
+        const response = await s3Config.client.send(new client_s3_1.GetObjectCommand({
+            Bucket: s3Config.bucket,
+            Key: key,
+            Range: `bytes=0-${byteCount - 1}`,
+        }));
+        const body = response.Body;
+        if (!body)
+            return Buffer.alloc(0);
+        const chunks = [];
+        for await (const chunk of body) {
+            chunks.push(Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+    catch (e) {
+        if (e.name === 'NoSuchKey' || e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404) {
+            return null;
+        }
+        throw e;
+    }
+}
 /**
  * Check if an object exists in S3 and optionally verify its content-type.
  *

package/types.d.ts

@@ -70,8 +70,19 @@ export interface StorageModuleConfig {
  * Input for the requestUploadUrl mutation.
  */
 export interface RequestUploadUrlInput {
-    /** Bucket key (e.g., "public", "private") */
-    bucketKey: string;
+    /**
+     * Logical bucket key (e.g., "public", "private").
+     *
+     * Optional: when omitted the database resolves its own default bucket for the
+     * requested access (see `isPublic`), so a client never has to know a tenant's
+     * bucket naming to upload.
+     */
+    bucketKey?: string;
+    /**
+     * Which default bucket to resolve when `bucketKey` is omitted: the public one
+     * (true) or the private one (default false). Ignored when `bucketKey` is given.
+     */
+    isPublic?: boolean;
     /**
      * Owner entity ID for entity-scoped uploads.
      * Omit for app-level (database-wide) storage.
@@ -111,6 +122,27 @@ export interface RequestUploadUrlPayload {
     expiresAt: string | null;
     /** ID of the previous version (set when re-uploading to an existing custom key) */
     previousVersionId: string | null;
+    /**
+     * The projection document to store in an `image`/`upload` column.
+     *
+     * Its `id` is the files row, which is what makes the column a reference the
+     * server can count — storage GC will not collect an object while a registered
+     * document column still names its file.
+     */
+    file: FileProjection;
+}
+/**
+ * The document a managed `image`/`upload` column stores. See `./managed-upload`.
+ */
+export interface FileProjection {
+    id: string;
+    key: string;
+    bucket_id: string;
+    mime: string;
+    size: number;
+    filename?: string;
+    /** @deprecated Read the files row's `downloadUrl` via `id` instead. */
+    url?: string;
 }
 /**
  * S3 configuration for the presigned URL plugin.