graphile-presigned-url-plugin 1.11.4 → 1.13.0

package/esm/managed-upload.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The managed upload lifecycle, shared by both transports.
+ *
+ * Multipart-through-GraphQL and presigned two-step are transports for one
+ * lifecycle, not two data models: either way an object gets a files row, a
+ * server-chosen key, a tenant-resolved bucket, and a projection document that
+ * carries the files row's id. The only difference is who moves the bytes.
+ *
+ * This module owns the parts that are the same:
+ *   * `resolveManagedUploadTarget` — from a document column to a concrete
+ *     (storage module, bucket, physical bucket, S3 config).
+ *   * `finalizeStagedUpload` — from bytes already in S3 under a staging key to a
+ *     files row and a projection document, deduplicating on content hash.
+ *   * `buildFileProjection` — the document shape the column stores.
+ *
+ * Nothing here bakes a presigned URL into a row: `url` is populated only for a
+ * public bucket, where it is a stable CDN address rather than a credential with
+ * an expiry.
+ */
+import { type FileRefFieldBinding } from './file-ref-registry';
+import { type WithPgClient } from './request-pg-client';
+import type { BucketConfig, FileProjection, PresignedUrlPluginOptions, S3Config, StorageModuleConfig } from './types';
+/**
+ * The document a managed `image`/`upload` column stores.
+ *
+ * `id` is the files row — the load-bearing field: it is what makes the column a
+ * projection rather than a second, unmanaged copy of the truth, and it is what
+ * storage GC counts before collecting an object.
+ *
+ * `url` is retained for existing readers of the pre-managed shape and is set
+ * only for public buckets. Prefer `id` plus the files row's `downloadUrl`, which
+ * is late-bound and works for private buckets too.
+ */
+export type { FileProjection } from './types';
+/**
+ * Build the projection document for a files row.
+ *
+ * A public bucket has a stable address, so `url` is a real, durable value there.
+ * A private bucket has no such address — only presigned, expiring ones — so the
+ * field is omitted rather than filled with a URL that dies in an hour.
+ */
+export declare function buildFileProjection(file: {
+    id: string;
+    key: string;
+    bucketId: string;
+    mime: string;
+    size: number;
+    filename?: string | null;
+}, bucket: {
+    is_public: boolean;
+}, s3: S3Config): FileProjection;
+/**
+ * Everything a managed upload needs before bytes move.
+ */
+export interface ManagedUploadTarget {
+    databaseId: string;
+    storageConfig: StorageModuleConfig;
+    bucket: BucketConfig;
+    physicalName: string;
+    s3: S3Config;
+    /** The registry row, or null when the column predates registration. */
+    binding: FileRefFieldBinding | null;
+}
+/**
+ * Resolve where a write to a document column lands.
+ *
+ * Two routes, one rule — the bucket is always resolved inside the tenant:
+ *   * a registered column names its storage module, and either a logical bucket
+ *     key or the reserved default tag for its declared publicness;
+ *   * an unregistered column (a bare `image`/`upload` on a database provisioned
+ *     before the registry) falls back to the app-scope module and the same
+ *     reserved default tag. That is a *tenant* default, not an environment one.
+ *
+ * A database with no storage module raises: there is nowhere tenant-owned to put
+ * the bytes, and the deployment's configured bucket is not an answer.
+ */
+export declare function resolveManagedUploadTarget(args: {
+    options: PresignedUrlPluginOptions;
+    withPgClient: WithPgClient;
+    pgSettings: Record<string, string> | null;
+    databaseId: string;
+    field: {
+        schemaName: string;
+        tableName: string;
+        columnName: string;
+    };
+    /** Publicness to use when the column is unregistered. */
+    defaultPublicAccess: boolean;
+}): Promise<ManagedUploadTarget>;
+/**
+ * Validate an upload against the resolved bucket's rules.
+ *
+ * The same rules the presigned lane enforces — a transport must not be a way
+ * around a bucket's mime allowlist or size cap.
+ */
+export declare function assertUploadAllowedByBucket(target: ManagedUploadTarget, contentType: string, size: number): void;
+/**
+ * Turn bytes already staged in S3 into a files row and a projection document.
+ *
+ * The content hash is only known once the stream has been read, so a streaming
+ * transport writes to a staging key first and promotes here:
+ *
+ *   * hash already present in this bucket → drop the staged object, reuse the
+ *     existing files row. Dedup is a property of the object, so it holds no
+ *     matter which transport wrote it first.
+ *   * otherwise → server-side copy to the content-addressed key, drop the staged
+ *     object, insert the files row.
+ *
+ * The row is inserted *after* the bytes land, so the confirm-upload job the
+ * insert trigger enqueues finds the object and completes the
+ * `requested → uploaded` transition without any extra wiring here.
+ *
+ * Every failure path leaves S3 as it found it. Bytes written by this call and
+ * not reachable through a files row would be invisible to storage GC, which
+ * collects objects by walking rows — so an object is only left behind once the
+ * row naming it exists.
+ */
+export declare function finalizeStagedUpload(args: {
+    target: ManagedUploadTarget;
+    withPgClient: WithPgClient;
+    pgSettings: Record<string, string> | null;
+    staged: {
+        stagingKey: string;
+        contentHash: string;
+        contentType: string;
+        size: number;
+        filename?: string | null;
+    };
+}): Promise<{
+    projection: FileProjection;
+    deduplicated: boolean;
+}>;

package/esm/managed-upload.js

@@ -0,0 +1,262 @@
+/**
+ * The managed upload lifecycle, shared by both transports.
+ *
+ * Multipart-through-GraphQL and presigned two-step are transports for one
+ * lifecycle, not two data models: either way an object gets a files row, a
+ * server-chosen key, a tenant-resolved bucket, and a projection document that
+ * carries the files row's id. The only difference is who moves the bytes.
+ *
+ * This module owns the parts that are the same:
+ *   * `resolveManagedUploadTarget` — from a document column to a concrete
+ *     (storage module, bucket, physical bucket, S3 config).
+ *   * `finalizeStagedUpload` — from bytes already in S3 under a staging key to a
+ *     files row and a projection document, deduplicating on content hash.
+ *   * `buildFileProjection` — the document shape the column stores.
+ *
+ * Nothing here bakes a presigned URL into a row: `url` is populated only for a
+ * public bucket, where it is a stable CDN address rather than a credential with
+ * an expiry.
+ */
+import { Logger } from '@pgpmjs/logger';
+import { resolveDefaultBucket } from './default-bucket';
+import { getFileRefFieldBinding } from './file-ref-registry';
+import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
+import { withRequestPgClient } from './request-pg-client';
+import { copyS3Object, deleteS3Object } from './s3-signer';
+import { getBucketConfig, loadAllStorageModules } from './storage-module-cache';
+const log = new Logger('graphile-presigned-url:managed-upload');
+/**
+ * Build the projection document for a files row.
+ *
+ * A public bucket has a stable address, so `url` is a real, durable value there.
+ * A private bucket has no such address — only presigned, expiring ones — so the
+ * field is omitted rather than filled with a URL that dies in an hour.
+ */
+export function buildFileProjection(file, bucket, s3) {
+    const projection = {
+        id: file.id,
+        key: file.key,
+        bucket_id: file.bucketId,
+        mime: file.mime,
+        size: file.size,
+    };
+    if (file.filename)
+        projection.filename = file.filename;
+    if (bucket.is_public && s3.publicUrlPrefix) {
+        projection.url = `${s3.publicUrlPrefix.replace(/\/$/, '')}/${file.key}`;
+    }
+    return projection;
+}
+/**
+ * Resolve where a write to a document column lands.
+ *
+ * Two routes, one rule — the bucket is always resolved inside the tenant:
+ *   * a registered column names its storage module, and either a logical bucket
+ *     key or the reserved default tag for its declared publicness;
+ *   * an unregistered column (a bare `image`/`upload` on a database provisioned
+ *     before the registry) falls back to the app-scope module and the same
+ *     reserved default tag. That is a *tenant* default, not an environment one.
+ *
+ * A database with no storage module raises: there is nowhere tenant-owned to put
+ * the bytes, and the deployment's configured bucket is not an answer.
+ */
+export async function resolveManagedUploadTarget(args) {
+    const { options, withPgClient, pgSettings, databaseId, field, defaultPublicAccess } = args;
+    // Registry and module registration are schema metadata, not tenant rows:
+    // read them in the system lane, like every other config read here.
+    const binding = await withPgClient(null, async (pgClient) => {
+        try {
+            return await getFileRefFieldBinding(pgClient, databaseId, field);
+        }
+        catch (err) {
+            // An unregistered column is a legitimate state (it predates the registry)
+            // and falls back to the tenant's app-scope default below. Any other
+            // failure — a broken connection, a missing registry table — is not.
+            if (err?.name === 'FileRefFieldNotRegisteredError')
+                return null;
+            throw err;
+        }
+    });
+    const allConfigs = await withPgClient(null, (pgClient) => loadAllStorageModules(pgClient, databaseId));
+    const storageConfig = binding
+        ? allConfigs.find((c) => c.id === binding.storageModuleId)
+        : allConfigs.find((c) => c.scope === 'app');
+    if (!storageConfig) {
+        throw new Error(binding
+            ? `STORAGE_MODULE_NOT_FOUND: file_ref_field ${binding.id} names storage module ` +
+                `${binding.storageModuleId}, which database ${databaseId} does not have`
+            : `STORAGE_MODULE_NOT_FOUND: ${field.schemaName}.${field.tableName}.${field.columnName} is an ` +
+                `unregistered upload column and database ${databaseId} has no app-scope storage module to ` +
+                'default to; there is no environment bucket to fall back to');
+    }
+    if (storageConfig.scope !== 'app') {
+        // An entity-scoped module resolves its bucket per owning row, and a
+        // multipart column write does not carry one. Refuse rather than write a
+        // tenant's file into whichever bucket happened to resolve.
+        throw new Error(`STORAGE_SCOPE_UNSUPPORTED: ${field.schemaName}.${field.tableName}.${field.columnName} binds to ` +
+            `'${storageConfig.scope}'-scoped storage, which resolves its bucket per owner row. ` +
+            'Use the presigned upload mutation, which takes an ownerId.');
+    }
+    const publicAccess = binding?.isPublic ?? defaultPublicAccess;
+    // Bucket resolution and the bucket read run under the request role: what the
+    // caller may store into is exactly what RLS lets them see.
+    const coordinate = await withRequestPgClient(withPgClient, pgSettings, (pgClient) => resolveDefaultBucket(pgClient, databaseId, storageConfig.scope, null, publicAccess, binding?.bucketKey ?? null));
+    const bucket = await withRequestPgClient(withPgClient, pgSettings, (pgClient) => getBucketConfig(pgClient, storageConfig, databaseId, coordinate.resolvedKey));
+    if (!bucket) {
+        throw new Error(`BUCKET_NOT_FOUND: bucket "${coordinate.resolvedKey}" resolved for ` +
+            `${field.schemaName}.${field.tableName}.${field.columnName} is not readable`);
+    }
+    if (bucket.allow_custom_keys) {
+        // A path-keyed bucket (e.g. a static site's) is addressed by the keys its
+        // publisher chose; this lane can only mint content-hash keys, which would
+        // pollute it with unreachable objects. Path-keyed uploads go through the
+        // presigned lane, which accepts an explicit `key`.
+        throw new Error(`BUCKET_PATH_KEYED: bucket "${bucket.key}" allows custom keys and is addressed by path; ` +
+            'the multipart upload lane only writes content-addressed keys. Use the presigned upload ' +
+            'mutation with an explicit key.');
+    }
+    const physicalName = bucket.physical_name === null
+        ? await provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+        : bucket.physical_name;
+    return {
+        databaseId,
+        storageConfig,
+        bucket,
+        physicalName,
+        s3: resolveS3ForDatabase(options, storageConfig, physicalName),
+        binding,
+    };
+}
+/**
+ * Validate an upload against the resolved bucket's rules.
+ *
+ * The same rules the presigned lane enforces — a transport must not be a way
+ * around a bucket's mime allowlist or size cap.
+ */
+export function assertUploadAllowedByBucket(target, contentType, size) {
+    const { bucket, storageConfig } = target;
+    if (bucket.allowed_mime_types && bucket.allowed_mime_types.length > 0) {
+        const isAllowed = bucket.allowed_mime_types.some((pattern) => {
+            if (pattern === '*/*')
+                return true;
+            if (pattern.endsWith('/*'))
+                return contentType.startsWith(pattern.slice(0, -1));
+            return contentType === pattern;
+        });
+        if (!isAllowed) {
+            throw new Error(`CONTENT_TYPE_NOT_ALLOWED: ${contentType} not in bucket allowed types`);
+        }
+    }
+    const maxSize = bucket.max_file_size ?? storageConfig.defaultMaxFileSize;
+    if (size > maxSize) {
+        throw new Error(`FILE_TOO_LARGE: ${size} bytes exceeds the ${maxSize} byte limit`);
+    }
+    if (size <= 0) {
+        throw new Error('INVALID_FILE_SIZE: an upload must carry at least one byte');
+    }
+}
+/** Delete an object we are abandoning, without masking the failure in progress. */
+async function bestEffortDelete(s3, key) {
+    try {
+        await deleteS3Object(s3, key);
+    }
+    catch (err) {
+        log.warn(`Failed to clean up abandoned object ${key}: ${err}`);
+    }
+}
+/**
+ * Turn bytes already staged in S3 into a files row and a projection document.
+ *
+ * The content hash is only known once the stream has been read, so a streaming
+ * transport writes to a staging key first and promotes here:
+ *
+ *   * hash already present in this bucket → drop the staged object, reuse the
+ *     existing files row. Dedup is a property of the object, so it holds no
+ *     matter which transport wrote it first.
+ *   * otherwise → server-side copy to the content-addressed key, drop the staged
+ *     object, insert the files row.
+ *
+ * The row is inserted *after* the bytes land, so the confirm-upload job the
+ * insert trigger enqueues finds the object and completes the
+ * `requested → uploaded` transition without any extra wiring here.
+ *
+ * Every failure path leaves S3 as it found it. Bytes written by this call and
+ * not reachable through a files row would be invisible to storage GC, which
+ * collects objects by walking rows — so an object is only left behind once the
+ * row naming it exists.
+ */
+export async function finalizeStagedUpload(args) {
+    const { target, withPgClient, pgSettings, staged } = args;
+    const { storageConfig, bucket, s3 } = target;
+    assertUploadAllowedByBucket(target, staged.contentType, staged.size);
+    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
+             FROM ${storageConfig.filesQualifiedName}
+             WHERE content_hash = $1 AND bucket_id = $2
+             LIMIT 1`,
+            values: [staged.contentHash, bucket.id],
+        });
+        return result.rows[0];
+    });
+    if (existing) {
+        log.info(`Dedup hit: file ${existing.id} already carries hash ${staged.contentHash}`);
+        await deleteS3Object(s3, staged.stagingKey);
+        return {
+            projection: buildFileProjection({
+                id: existing.id,
+                key: existing.key,
+                bucketId: bucket.id,
+                mime: existing.mime_type,
+                size: Number(existing.size),
+                filename: existing.filename,
+            }, bucket, s3),
+            deduplicated: true,
+        };
+    }
+    await copyS3Object(s3, staged.stagingKey, finalKey, staged.contentType);
+    let fileId;
+    try {
+        fileId = await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
+            const result = await pgClient.query({
+                text: `INSERT INTO ${storageConfig.filesQualifiedName}
+             (bucket_id, key, content_hash, mime_type, size, filename, is_public)
+             VALUES ($1, $2, $3, $4, $5, $6, $7)
+             RETURNING id`,
+                values: [
+                    bucket.id,
+                    finalKey,
+                    staged.contentHash,
+                    staged.contentType,
+                    staged.size,
+                    staged.filename ?? null,
+                    bucket.is_public,
+                ],
+            });
+            return result.rows[0].id;
+        });
+    }
+    catch (err) {
+        // No row names either key, so both are unreachable to GC. Dropping the
+        // promoted copy is safe precisely because the dedup probe above found no row
+        // on this hash: nothing else in this bucket is entitled to those bytes.
+        // Cleanup must never replace the failure that caused it.
+        await bestEffortDelete(s3, finalKey);
+        await bestEffortDelete(s3, staged.stagingKey);
+        throw err;
+    }
+    await deleteS3Object(s3, staged.stagingKey);
+    log.info(`Managed upload created file ${fileId} at ${bucket.key}/${finalKey}`);
+    return {
+        projection: buildFileProjection({
+            id: fileId,
+            key: finalKey,
+            bucketId: bucket.id,
+            mime: staged.contentType,
+            size: staged.size,
+            filename: staged.filename,
+        }, bucket, s3),
+        deduplicated: false,
+    };
+}

package/esm/physical-bucket.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Physical bucket coordinates: minting a name once, recording it, and building
+ * an S3 config against a *known* name.
+ *
+ * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
+ * mapping is recorded on the bucket row the first time it is provisioned, and
+ * from then on the recorded value is the only coordinate anything reads — no
+ * name is ever recomputed from a prefix convention, and there is no
+ * environment-level bucket standing in for a tenant's.
+ */
+import { type WithPgClient } from './request-pg-client';
+import type { BucketConfig, PresignedUrlPluginOptions, S3Config, StorageModuleConfig } from './types';
+/**
+ * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
+ * a lazy getter on first use.
+ *
+ * `s3.bucket` on the result is the deployment's *default* physical bucket. It is
+ * a connection default only — never a tenant's bucket. Every upload path
+ * resolves its physical bucket from the tenant's bucket row.
+ */
+export declare function resolveS3(options: PresignedUrlPluginOptions): S3Config;
+/**
+ * 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.
+ *
+ * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
+ * name is not a tenant's storage, and silently minting one is how objects ended
+ * up in a bucket no database owned. A deployment that wants per-tenant buckets
+ * must supply the policy.
+ */
+export declare function mintPhysicalBucketName(options: PresignedUrlPluginOptions, databaseId: string, bucketKey: string): string;
+/**
+ * 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.
+ */
+export declare function resolveS3ForDatabase(options: PresignedUrlPluginOptions, storageConfig: StorageModuleConfig, physicalName: string): S3Config;
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function provisionAndRecordPhysicalBucket(options: PresignedUrlPluginOptions, withPgClient: WithPgClient, storageConfig: StorageModuleConfig, databaseId: string, bucket: BucketConfig, allowedOrigins: string[] | null): Promise<string>;

package/esm/physical-bucket.js

@@ -0,0 +1,111 @@
+/**
+ * Physical bucket coordinates: minting a name once, recording it, and building
+ * an S3 config against a *known* name.
+ *
+ * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
+ * mapping is recorded on the bucket row the first time it is provisioned, and
+ * from then on the recorded value is the only coordinate anything reads — no
+ * name is ever recomputed from a prefix convention, and there is no
+ * environment-level bucket standing in for a tenant's.
+ */
+import { Logger } from '@pgpmjs/logger';
+import { withRequestPgClient } from './request-pg-client';
+import { isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
+const log = new Logger('graphile-presigned-url:physical-bucket');
+/**
+ * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
+ * a lazy getter on first use.
+ *
+ * `s3.bucket` on the result is the deployment's *default* physical bucket. It is
+ * a connection default only — never a tenant's bucket. Every upload path
+ * resolves its physical bucket from the tenant's bucket row.
+ */
+export 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.
+ *
+ * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
+ * name is not a tenant's storage, and silently minting one is how objects ended
+ * up in a bucket no database owned. A deployment that wants per-tenant buckets
+ * must supply the policy.
+ */
+export function mintPhysicalBucketName(options, databaseId, bucketKey) {
+    if (!options.resolveBucketName) {
+        throw new Error('STORAGE_BUCKET_NAME_POLICY_MISSING: no resolveBucketName was configured, so there is ' +
+            `no name to provision for bucket "${bucketKey}" of database ${databaseId}. ` +
+            'Physical bucket naming is a deployment policy; the configured s3.bucket is a ' +
+            'connection default and is never a tenant bucket.');
+    }
+    return options.resolveBucketName(databaseId, bucketKey);
+}
+/**
+ * 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.
+ */
+export 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.
+ *
+ * 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.
+ */
+export async function provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, allowedOrigins) {
+    const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
+    if (options.ensureBucketProvisioned && !isS3BucketProvisioned(s3BucketName)) {
+        log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
+        await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
+        markS3BucketProvisioned(s3BucketName);
+        log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
+    }
+    // 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 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;
+}