graphile-presigned-url-plugin 1.11.4 → 1.13.0

package/esm/plugin.js

@@ -19,9 +19,13 @@
 import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
 import { access, context as grafastContext, lambda, object } from 'grafast';
+import { checkTypeAgreement } from 'mime-bytes';
+import { resolveDefaultBucket } from './default-bucket';
+import { buildFileProjection } from './managed-upload';
+import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
 import { deleteS3Object, generatePresignedPutUrl } from './s3-signer';
-import { getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, storedPhysicalName } from './storage-module-cache';
+import { getBucketConfig, loadAllStorageModules, resolveStorageConfigFromCodec, storedPhysicalName } from './storage-module-cache';
 const log = new Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
 const MAX_CONTENT_HASH_LENGTH = 128;
@@ -67,87 +71,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 && !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`);
+async function resolveUploadBucket(pgClient, storageConfig, databaseId, bucketKey, ownerId, isPublic) {
+    if (bucketKey) {
+        return 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 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 resolveDefaultBucket(pgClient, databaseId, storageConfig.scope, ownerId, isPublic, null);
+    return getBucketConfig(pgClient, storageConfig, databaseId, coordinate.resolvedKey, ownerId || undefined);
 }
 // --- Plugin factory ---
 export function createPresignedUrlPlugin(options) {
@@ -166,6 +103,14 @@ export 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;
@@ -199,7 +144,8 @@ export 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)' } }
                                     : {}),
@@ -219,6 +165,16 @@ export 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;
@@ -232,6 +188,7 @@ export function createPresignedUrlPlugin(options) {
                             plan(_$mutation, fieldArgs) {
                                 const $input = fieldArgs.getRaw('input');
                                 const $bucketKey = access($input, 'bucketKey');
+                                const $isPublic = access($input, 'isPublic');
                                 const $contentHash = access($input, 'contentHash');
                                 const $contentType = access($input, 'contentType');
                                 const $size = access($input, 'size');
@@ -242,6 +199,7 @@ export function createPresignedUrlPlugin(options) {
                                 const $pgSettings = grafastContext().get('pgSettings');
                                 const $combined = object({
                                     bucketKey: $bucketKey,
+                                    isPublic: $isPublic,
                                     ownerId: $ownerId,
                                     contentHash: $contentHash,
                                     contentType: $contentType,
@@ -264,8 +222,8 @@ export function createPresignedUrlPlugin(options) {
                                     const storageConfig = 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 withRequestPgClient(vals.withPgClient, vals.pgSettings, (pgClient) => getBucketConfig(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    // Bucket resolution + read under the request role (RLS-gated visibility).
+                                    const bucket = await 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
@@ -305,12 +263,14 @@ export 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)' } }
                                     : {}),
@@ -334,12 +294,14 @@ export function createPresignedUrlPlugin(options) {
                             plan(_$mutation, fieldArgs) {
                                 const $input = fieldArgs.getRaw('input');
                                 const $bucketKey = access($input, 'bucketKey');
+                                const $isPublic = access($input, 'isPublic');
                                 const $ownerId = hasOwnerId ? access($input, 'ownerId') : lambda(null, () => null);
                                 const $files = access($input, 'files');
                                 const $withPgClient = grafastContext().get('withPgClient');
                                 const $pgSettings = grafastContext().get('pgSettings');
                                 const $combined = object({
                                     bucketKey: $bucketKey,
+                                    isPublic: $isPublic,
                                     ownerId: $ownerId,
                                     files: $files,
                                     withPgClient: $withPgClient,
@@ -358,8 +320,8 @@ export function createPresignedUrlPlugin(options) {
                                     const storageConfig = 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 withRequestPgClient(vals.withPgClient, vals.pgSettings, (pgClient) => getBucketConfig(pgClient, storageConfig, databaseId, vals.bucketKey, vals.ownerId || undefined));
+                                    // Bucket resolution + read under the request role (RLS-gated visibility).
+                                    const bucket = await 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
@@ -544,6 +506,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 = 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;
@@ -564,6 +536,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) => buildFileProjection({ id: fileId, key, bucketId: bucket.id, mime: contentType, size, filename }, bucket, s3ForDb);
     // Determine S3 key
     let s3Key;
     let isCustomKey = false;
@@ -604,6 +581,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
                     deduplicated: true,
                     expiresAt: null,
                     previousVersionId: null,
+                    file: projectFile(existing.id, s3Key),
                 };
             }
             previousVersionId = existing.id;
@@ -629,6 +607,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
                 deduplicated: true,
                 expiresAt: null,
                 previousVersionId: null,
+                file: projectFile(existingFile.id, s3Key),
             };
         }
     }
@@ -669,6 +648,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         deduplicated: false,
         expiresAt,
         previousVersionId,
+        file: projectFile(fileId, s3Key),
     };
 }
 export const PresignedUrlPlugin = createPresignedUrlPlugin;

package/esm/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/esm/s3-signer.js

@@ -1,4 +1,4 @@
-import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, } from '@aws-sdk/client-s3';
+import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { Logger } from '@pgpmjs/logger';
 const log = new Logger('graphile-presigned-url:s3');
@@ -68,6 +68,66 @@ export 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
+ */
+export async function copyS3Object(s3Config, sourceKey, destinationKey, contentType) {
+    await s3Config.client.send(new 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
+ */
+export async function readObjectPrefix(s3Config, key, byteCount) {
+    try {
+        const response = await s3Config.client.send(new 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/esm/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.

package/file-ref-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The `file_ref_field` registry: which storage module and bucket a managed
+ * document column writes into.
+ *
+ * An `image`/`upload` column is a projection of a files row, and the decision of
+ * *where* those bytes live is a property of the field declaration, not of the
+ * request. The registry records that intent per (table, column) — a storage
+ * module plus either a logical bucket key, a tag selector, or nothing at all
+ * (meaning the reserved default tag for the declared publicness).
+ *
+ * This module answers one question — "what does a write to this column bind
+ * to?" — and answers it loudly: an unregistered column raises rather than
+ * falling back to a server-global bucket, because a silent fallback is how the
+ * unmanaged lane produced objects no tenant owned.
+ */
+/**
+ * A field's recorded storage intent.
+ *
+ * `bucketKey` and `bucketTags` are mutually exclusive by table constraint, and
+ * both may be absent — resolution then uses the reserved default tag for
+ * `isPublic`. Nothing here is a physical bucket name or id: the concrete bucket
+ * is resolved per written row, inside the tenant.
+ */
+export interface FileRefFieldBinding {
+    id: string;
+    storageModuleId: string;
+    bucketKey: string | null;
+    bucketTags: string[] | null;
+    isPublic: boolean | null;
+    enforceFk: boolean;
+}
+export declare class FileRefFieldNotRegisteredError extends Error {
+    readonly databaseId: string;
+    readonly schemaName: string;
+    readonly tableName: string;
+    readonly columnName: string;
+    constructor(databaseId: string, schemaName: string, tableName: string, columnName: string);
+}
+/**
+ * Look up the storage binding for a document column, or throw.
+ *
+ * The read runs on whichever client the caller passes. The registry is schema
+ * metadata rather than tenant rows, so callers resolve it in the system lane —
+ * the RLS that matters is on the files table the upload eventually writes.
+ */
+export declare function getFileRefFieldBinding(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, field: {
+    schemaName: string;
+    tableName: string;
+    columnName: string;
+}): Promise<FileRefFieldBinding>;
+/**
+ * Drop cached bindings. Used by tests and after a re-provision.
+ */
+export declare function clearFileRefFieldCache(): void;

package/file-ref-registry.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * The `file_ref_field` registry: which storage module and bucket a managed
+ * document column writes into.
+ *
+ * An `image`/`upload` column is a projection of a files row, and the decision of
+ * *where* those bytes live is a property of the field declaration, not of the
+ * request. The registry records that intent per (table, column) — a storage
+ * module plus either a logical bucket key, a tag selector, or nothing at all
+ * (meaning the reserved default tag for the declared publicness).
+ *
+ * This module answers one question — "what does a write to this column bind
+ * to?" — and answers it loudly: an unregistered column raises rather than
+ * falling back to a server-global bucket, because a silent fallback is how the
+ * unmanaged lane produced objects no tenant owned.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRefFieldNotRegisteredError = void 0;
+exports.getFileRefFieldBinding = getFileRefFieldBinding;
+exports.clearFileRefFieldCache = clearFileRefFieldCache;
+const logger_1 = require("@pgpmjs/logger");
+const lru_cache_1 = require("lru-cache");
+const log = new logger_1.Logger('graphile-presigned-url:file-ref-registry');
+const FIVE_MINUTES_MS = 1000 * 60 * 5;
+const ONE_HOUR_MS = 1000 * 60 * 60;
+/**
+ * Resolve the registry row for a document column.
+ *
+ * Joined through metaschema rather than keyed by name, because the registry
+ * records field *ids*: the physical (schema, table, column) triple is what the
+ * GraphQL layer knows, and metaschema is the only thing that maps one to the
+ * other.
+ */
+const FILE_REF_FIELD_QUERY = `
+  SELECT
+    frf.id,
+    frf.storage_module_id,
+    frf.bucket_key,
+    frf.bucket_tags::text[] AS bucket_tags,
+    frf.is_public,
+    frf.enforce_fk
+  FROM metaschema_modules_public.file_ref_field frf
+  JOIN metaschema_public.field f ON f.id = frf.field_id
+  JOIN metaschema_public.table t ON t.id = frf.table_id
+  JOIN metaschema_public.schema s ON s.id = t.schema_id
+  WHERE frf.database_id = $1
+    AND s.schema_name = $2
+    AND t.name = $3
+    AND f.name = $4
+  LIMIT 1
+`;
+/**
+ * LRU cache of field bindings.
+ *
+ * A binding is schema, not data: it changes only when a database is
+ * re-provisioned, so it caches on the same terms as the storage module config
+ * next to it. Misses are never cached — an unregistered column is a hard error
+ * every time it is written, not a remembered "no".
+ */
+const bindingCache = new lru_cache_1.LRUCache({
+    max: 500,
+    ttl: process.env.NODE_ENV === 'development' ? FIVE_MINUTES_MS : ONE_HOUR_MS,
+    updateAgeOnGet: true,
+});
+class FileRefFieldNotRegisteredError extends Error {
+    databaseId;
+    schemaName;
+    tableName;
+    columnName;
+    constructor(databaseId, schemaName, tableName, columnName) {
+        super(`FILE_REF_FIELD_NOT_REGISTERED: ${schemaName}.${tableName}.${columnName} ` +
+            `is not a registered file-reference field in database ${databaseId}. ` +
+            'A managed upload needs the declared storage module and bucket intent; ' +
+            'there is no server-global bucket to fall back to.');
+        this.databaseId = databaseId;
+        this.schemaName = schemaName;
+        this.tableName = tableName;
+        this.columnName = columnName;
+        this.name = 'FileRefFieldNotRegisteredError';
+    }
+}
+exports.FileRefFieldNotRegisteredError = FileRefFieldNotRegisteredError;
+/**
+ * Look up the storage binding for a document column, or throw.
+ *
+ * The read runs on whichever client the caller passes. The registry is schema
+ * metadata rather than tenant rows, so callers resolve it in the system lane —
+ * the RLS that matters is on the files table the upload eventually writes.
+ */
+async function getFileRefFieldBinding(pgClient, databaseId, field) {
+    const cacheKey = `file-ref:${databaseId}:${field.schemaName}.${field.tableName}.${field.columnName}`;
+    const cached = bindingCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const result = await pgClient.query({
+        text: FILE_REF_FIELD_QUERY,
+        values: [databaseId, field.schemaName, field.tableName, field.columnName],
+    });
+    if (result.rows.length === 0) {
+        throw new FileRefFieldNotRegisteredError(databaseId, field.schemaName, field.tableName, field.columnName);
+    }
+    const row = result.rows[0];
+    const binding = {
+        id: row.id,
+        storageModuleId: row.storage_module_id,
+        bucketKey: row.bucket_key,
+        bucketTags: row.bucket_tags,
+        isPublic: row.is_public,
+        enforceFk: row.enforce_fk,
+    };
+    bindingCache.set(cacheKey, binding);
+    log.debug(`Bound ${field.schemaName}.${field.tableName}.${field.columnName} to storage module ` +
+        `${binding.storageModuleId} (bucket_key=${binding.bucketKey ?? '<default tag>'})`);
+    return binding;
+}
+/**
+ * Drop cached bindings. Used by tests and after a re-provision.
+ */
+function clearFileRefFieldCache() {
+    bindingCache.clear();
+}

package/index.d.ts

@@ -26,9 +26,17 @@
  * };
  * ```
  */
+export { CONFIRM_PREFIX_BYTES, confirmUploadedBytes, type ConfirmUploadInput, type ConfirmUploadVerdict, } from './confirm-upload';
+export type { ResolvedBucketCoordinate } from './default-bucket';
+export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
+export type { FileRefFieldBinding } from './file-ref-registry';
+export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
+export { assertUploadAllowedByBucket, buildFileProjection, type FileProjection, finalizeStagedUpload, type ManagedUploadTarget, resolveManagedUploadTarget, } from './managed-upload';
+export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, resolveS3ForDatabase } from './physical-bucket';
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
-export { deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject } from './s3-signer';
+export { type WithPgClient, withRequestPgClient } from './request-pg-client';
+export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
 export { clearBucketCache, clearStorageModuleCache, getBucketConfig, getStorageModuleConfig, getStorageModuleConfigForOwner, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
 export type { BucketConfig, BucketNameResolver, EnsureBucketProvisioned, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';