graphile-presigned-url-plugin 1.11.4 → 1.13.0

package/index.js

@@ -28,19 +28,42 @@
  * ```
  */
 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.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.createDownloadUrlPlugin = 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.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 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");
 Object.defineProperty(exports, "createDownloadUrlPlugin", { enumerable: true, get: function () { return download_url_field_1.createDownloadUrlPlugin; } });
+var file_ref_registry_1 = require("./file-ref-registry");
+Object.defineProperty(exports, "clearFileRefFieldCache", { enumerable: true, get: function () { return file_ref_registry_1.clearFileRefFieldCache; } });
+Object.defineProperty(exports, "FileRefFieldNotRegisteredError", { enumerable: true, get: function () { return file_ref_registry_1.FileRefFieldNotRegisteredError; } });
+Object.defineProperty(exports, "getFileRefFieldBinding", { enumerable: true, get: function () { return file_ref_registry_1.getFileRefFieldBinding; } });
+var managed_upload_1 = require("./managed-upload");
+Object.defineProperty(exports, "assertUploadAllowedByBucket", { enumerable: true, get: function () { return managed_upload_1.assertUploadAllowedByBucket; } });
+Object.defineProperty(exports, "buildFileProjection", { enumerable: true, get: function () { return managed_upload_1.buildFileProjection; } });
+Object.defineProperty(exports, "finalizeStagedUpload", { enumerable: true, get: function () { return managed_upload_1.finalizeStagedUpload; } });
+Object.defineProperty(exports, "resolveManagedUploadTarget", { enumerable: true, get: function () { return managed_upload_1.resolveManagedUploadTarget; } });
+var physical_bucket_1 = require("./physical-bucket");
+Object.defineProperty(exports, "mintPhysicalBucketName", { enumerable: true, get: function () { return physical_bucket_1.mintPhysicalBucketName; } });
+Object.defineProperty(exports, "provisionAndRecordPhysicalBucket", { enumerable: true, get: function () { return physical_bucket_1.provisionAndRecordPhysicalBucket; } });
+Object.defineProperty(exports, "resolveS3", { enumerable: true, get: function () { return physical_bucket_1.resolveS3; } });
+Object.defineProperty(exports, "resolveS3ForDatabase", { enumerable: true, get: function () { return physical_bucket_1.resolveS3ForDatabase; } });
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "createPresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.createPresignedUrlPlugin; } });
 Object.defineProperty(exports, "PresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.PresignedUrlPlugin; } });
 var preset_1 = require("./preset");
 Object.defineProperty(exports, "PresignedUrlPreset", { enumerable: true, get: function () { return preset_1.PresignedUrlPreset; } });
+var request_pg_client_1 = require("./request-pg-client");
+Object.defineProperty(exports, "withRequestPgClient", { enumerable: true, get: function () { return request_pg_client_1.withRequestPgClient; } });
 var s3_signer_1 = require("./s3-signer");
+Object.defineProperty(exports, "copyS3Object", { enumerable: true, get: function () { return s3_signer_1.copyS3Object; } });
 Object.defineProperty(exports, "deleteS3Object", { enumerable: true, get: function () { return s3_signer_1.deleteS3Object; } });
 Object.defineProperty(exports, "generatePresignedGetUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedGetUrl; } });
 Object.defineProperty(exports, "generatePresignedPutUrl", { enumerable: true, get: function () { return s3_signer_1.generatePresignedPutUrl; } });
 Object.defineProperty(exports, "headObject", { enumerable: true, get: function () { return s3_signer_1.headObject; } });
+Object.defineProperty(exports, "readObjectPrefix", { enumerable: true, get: function () { return s3_signer_1.readObjectPrefix; } });
 var storage_module_cache_1 = require("./storage-module-cache");
 Object.defineProperty(exports, "clearBucketCache", { enumerable: true, get: function () { return storage_module_cache_1.clearBucketCache; } });
 Object.defineProperty(exports, "clearStorageModuleCache", { enumerable: true, get: function () { return storage_module_cache_1.clearStorageModuleCache; } });

package/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/managed-upload.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFileProjection = buildFileProjection;
+exports.resolveManagedUploadTarget = resolveManagedUploadTarget;
+exports.assertUploadAllowedByBucket = assertUploadAllowedByBucket;
+exports.finalizeStagedUpload = finalizeStagedUpload;
+const logger_1 = require("@pgpmjs/logger");
+const default_bucket_1 = require("./default-bucket");
+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");
+const s3_signer_1 = require("./s3-signer");
+const storage_module_cache_1 = require("./storage-module-cache");
+const log = new logger_1.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.
+ */
+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.
+ */
+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 (0, file_ref_registry_1.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) => (0, storage_module_cache_1.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 (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, (pgClient) => (0, default_bucket_1.resolveDefaultBucket)(pgClient, databaseId, storageConfig.scope, null, publicAccess, binding?.bucketKey ?? null));
+    const bucket = await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, (pgClient) => (0, storage_module_cache_1.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 (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
+        : bucket.physical_name;
+    return {
+        databaseId,
+        storageConfig,
+        bucket,
+        physicalName,
+        s3: (0, physical_bucket_1.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.
+ */
+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 (0, s3_signer_1.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.
+ */
+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 (0, request_pg_client_1.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 (0, s3_signer_1.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 (0, s3_signer_1.copyS3Object)(s3, staged.stagingKey, finalKey, staged.contentType);
+    let fileId;
+    try {
+        fileId = await (0, request_pg_client_1.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 (0, s3_signer_1.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.11.4",
+  "version": "1.13.0",
   "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",
@@ -44,7 +44,8 @@
     "@aws-sdk/s3-request-presigner": "^3.1052.0",
     "@pgpmjs/logger": "^2.24.1",
     "@pgsql/quotes": "^18.2.4",
-    "lru-cache": "^11.2.7"
+    "lru-cache": "^11.2.7",
+    "mime-bytes": "^0.31.0"
   },
   "peerDependencies": {
     "grafast": "^1.1.1",
@@ -60,5 +61,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "d6afee66ac3400e78864b9e259cdd6ab9184b251"
+  "gitHead": "d0d796b7eb0d16c8c19405a49c0ca62ce3df117b"
 }

package/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/physical-bucket.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveS3 = resolveS3;
+exports.mintPhysicalBucketName = mintPhysicalBucketName;
+exports.resolveS3ForDatabase = resolveS3ForDatabase;
+exports.provisionAndRecordPhysicalBucket = provisionAndRecordPhysicalBucket;
+const logger_1 = require("@pgpmjs/logger");
+const request_pg_client_1 = require("./request-pg-client");
+const storage_module_cache_1 = require("./storage-module-cache");
+const log = new logger_1.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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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`);
+    }
+    // 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;
+}