graphile-presigned-url-plugin 1.11.4 → 1.13.0

package/confirm-upload.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The byte-validating half of the presigned lane's confirmation.
+ *
+ * A presigned upload's bytes never pass through the server: the client PUTs them
+ * straight to S3, so at the moment the files row is written the only statements
+ * about the file are the client's own. `requested` is exactly that state — a
+ * claim — and the row must not reach `uploaded` until the bytes behind it have
+ * been looked at, because every downstream processing step (image versions,
+ * extraction, embeddings) fires on `uploaded` and would otherwise be handed
+ * whatever the client chose to upload.
+ *
+ * So confirmation answers three questions in order, and each has a distinct
+ * outcome on the row:
+ *
+ *   1. did the bytes arrive?          no  → `expired`  (the client walked away)
+ *   2. are they the file they claim?   no  → `rejected` (and the object deleted)
+ *   3. otherwise                           → `uploaded`
+ *
+ * The bytes are read with a ranged GET of the leading bytes, not downloaded: a
+ * magic-byte signature is in the first few dozen bytes, so this costs the same
+ * for a 2GB video as for an icon.
+ *
+ * This module is the decision, not the transition. The worker that owns the
+ * `storage:confirm_upload` job applies it by calling the generated
+ * `<files>_confirm_uploaded` / `_reject_file` / `_expire_file` functions — the
+ * verdict is returned rather than executed so that the same rule can be applied
+ * by any transport, and tested without a database.
+ */
+import type { S3Config } from './types';
+/**
+ * How many leading bytes to read. Signatures are far shorter than this; the
+ * margin covers formats whose signature sits at an offset (e.g. the `ftyp` box
+ * of an MP4) and gives charset detection enough text to work with.
+ */
+export declare const CONFIRM_PREFIX_BYTES = 4096;
+export interface ConfirmUploadInput {
+    s3: S3Config;
+    /** The object key the presigned PUT was signed for. */
+    key: string;
+    /** The MIME type the client declared when the row was created. */
+    declaredMime: string;
+    /** The filename recorded on the files row, if any. */
+    filename?: string | null;
+}
+export type ConfirmUploadVerdict = {
+    outcome: 'uploaded';
+    detectedMime: string | null;
+} | {
+    outcome: 'rejected';
+    reason: string;
+    detectedMime: string | null;
+} | {
+    outcome: 'expired';
+    reason: string;
+};
+/**
+ * Decide what should happen to a `requested` files row, from its object's bytes.
+ *
+ * A missing object is `expired` rather than `rejected`: nothing was uploaded, so
+ * there is nothing to reject, and the row's own retry/expiry budget governs how
+ * long the client has left. An empty object, by contrast, *was* written and is
+ * not a file.
+ */
+export declare function confirmUploadedBytes(input: ConfirmUploadInput): Promise<ConfirmUploadVerdict>;

package/confirm-upload.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * The byte-validating half of the presigned lane's confirmation.
+ *
+ * A presigned upload's bytes never pass through the server: the client PUTs them
+ * straight to S3, so at the moment the files row is written the only statements
+ * about the file are the client's own. `requested` is exactly that state — a
+ * claim — and the row must not reach `uploaded` until the bytes behind it have
+ * been looked at, because every downstream processing step (image versions,
+ * extraction, embeddings) fires on `uploaded` and would otherwise be handed
+ * whatever the client chose to upload.
+ *
+ * So confirmation answers three questions in order, and each has a distinct
+ * outcome on the row:
+ *
+ *   1. did the bytes arrive?          no  → `expired`  (the client walked away)
+ *   2. are they the file they claim?   no  → `rejected` (and the object deleted)
+ *   3. otherwise                           → `uploaded`
+ *
+ * The bytes are read with a ranged GET of the leading bytes, not downloaded: a
+ * magic-byte signature is in the first few dozen bytes, so this costs the same
+ * for a 2GB video as for an icon.
+ *
+ * This module is the decision, not the transition. The worker that owns the
+ * `storage:confirm_upload` job applies it by calling the generated
+ * `<files>_confirm_uploaded` / `_reject_file` / `_expire_file` functions — the
+ * verdict is returned rather than executed so that the same rule can be applied
+ * by any transport, and tested without a database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIRM_PREFIX_BYTES = void 0;
+exports.confirmUploadedBytes = confirmUploadedBytes;
+const mime_bytes_1 = require("mime-bytes");
+const mime_bytes_2 = require("mime-bytes");
+const s3_signer_1 = require("./s3-signer");
+/**
+ * How many leading bytes to read. Signatures are far shorter than this; the
+ * margin covers formats whose signature sits at an offset (e.g. the `ftyp` box
+ * of an MP4) and gives charset detection enough text to work with.
+ */
+exports.CONFIRM_PREFIX_BYTES = 4096;
+/**
+ * Decide what should happen to a `requested` files row, from its object's bytes.
+ *
+ * A missing object is `expired` rather than `rejected`: nothing was uploaded, so
+ * there is nothing to reject, and the row's own retry/expiry budget governs how
+ * long the client has left. An empty object, by contrast, *was* written and is
+ * not a file.
+ */
+async function confirmUploadedBytes(input) {
+    const { s3, key, declaredMime, filename } = input;
+    const prefix = await (0, s3_signer_1.readObjectPrefix)(s3, key, exports.CONFIRM_PREFIX_BYTES);
+    if (prefix === null) {
+        return { outcome: 'expired', reason: `no object at key ${key}: the upload never arrived` };
+    }
+    if (prefix.length === 0) {
+        return {
+            outcome: 'rejected',
+            reason: `object at key ${key} is empty; an upload must carry at least one byte`,
+            detectedMime: null,
+        };
+    }
+    const detected = await (0, mime_bytes_1.detectFromBuffer)(prefix);
+    const detectedMime = detected?.mimeType ?? null;
+    const agreement = (0, mime_bytes_2.checkTypeAgreement)({ filename, declaredMime, detectedMime });
+    if (!agreement.ok) {
+        return { outcome: 'rejected', reason: agreement.violation.message, detectedMime };
+    }
+    return { outcome: 'uploaded', detectedMime };
+}

package/default-bucket.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+/**
+ * The resolved bucket coordinate.
+ *
+ * `physicalName` is the recorded S3 bucket name, or null when the logical
+ * bucket has never been provisioned — the caller mints and records it then.
+ */
+export interface ResolvedBucketCoordinate {
+    bucketId: string;
+    resolvedKey: string;
+    bucketType: 'public' | 'private' | 'temp';
+    physicalName: string | null;
+}
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+export declare function resolveDefaultBucket(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, scope: string, entityId: string | null, publicAccess: boolean, bucketKey: string | null): Promise<ResolvedBucketCoordinate>;

package/default-bucket.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDefaultBucket = resolveDefaultBucket;
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('graphile-presigned-url:default-bucket');
+const RESOLVE_DEFAULT_BUCKET_QUERY = `
+  SELECT bucket_id, resolved_key, bucket_type, physical_name
+  FROM function_resolution.resolve_default_bucket($1, $2, $3, $4, $5)
+`;
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+async function resolveDefaultBucket(pgClient, databaseId, scope, entityId, publicAccess, bucketKey) {
+    const result = await pgClient.query({
+        text: RESOLVE_DEFAULT_BUCKET_QUERY,
+        values: [databaseId, scope, entityId, publicAccess, bucketKey],
+    });
+    const row = result.rows[0];
+    if (!row) {
+        // resolve_default_bucket raises on zero and on several matches, so an empty
+        // result means the function did not run as declared rather than "no bucket".
+        throw new Error(`STORAGE_DEFAULT_BUCKET_NO_ROW: resolve_default_bucket returned no row for ` +
+            `database=${databaseId} scope=${scope} public=${publicAccess} key=${bucketKey ?? '<default tag>'}`);
+    }
+    log.debug(`Resolved bucket ${row.resolved_key} (${row.bucket_type}) for database=${databaseId} scope=${scope}`);
+    return {
+        bucketId: row.bucket_id,
+        resolvedKey: row.resolved_key,
+        bucketType: row.bucket_type,
+        physicalName: row.physical_name,
+    };
+}

package/esm/confirm-upload.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The byte-validating half of the presigned lane's confirmation.
+ *
+ * A presigned upload's bytes never pass through the server: the client PUTs them
+ * straight to S3, so at the moment the files row is written the only statements
+ * about the file are the client's own. `requested` is exactly that state — a
+ * claim — and the row must not reach `uploaded` until the bytes behind it have
+ * been looked at, because every downstream processing step (image versions,
+ * extraction, embeddings) fires on `uploaded` and would otherwise be handed
+ * whatever the client chose to upload.
+ *
+ * So confirmation answers three questions in order, and each has a distinct
+ * outcome on the row:
+ *
+ *   1. did the bytes arrive?          no  → `expired`  (the client walked away)
+ *   2. are they the file they claim?   no  → `rejected` (and the object deleted)
+ *   3. otherwise                           → `uploaded`
+ *
+ * The bytes are read with a ranged GET of the leading bytes, not downloaded: a
+ * magic-byte signature is in the first few dozen bytes, so this costs the same
+ * for a 2GB video as for an icon.
+ *
+ * This module is the decision, not the transition. The worker that owns the
+ * `storage:confirm_upload` job applies it by calling the generated
+ * `<files>_confirm_uploaded` / `_reject_file` / `_expire_file` functions — the
+ * verdict is returned rather than executed so that the same rule can be applied
+ * by any transport, and tested without a database.
+ */
+import type { S3Config } from './types';
+/**
+ * How many leading bytes to read. Signatures are far shorter than this; the
+ * margin covers formats whose signature sits at an offset (e.g. the `ftyp` box
+ * of an MP4) and gives charset detection enough text to work with.
+ */
+export declare const CONFIRM_PREFIX_BYTES = 4096;
+export interface ConfirmUploadInput {
+    s3: S3Config;
+    /** The object key the presigned PUT was signed for. */
+    key: string;
+    /** The MIME type the client declared when the row was created. */
+    declaredMime: string;
+    /** The filename recorded on the files row, if any. */
+    filename?: string | null;
+}
+export type ConfirmUploadVerdict = {
+    outcome: 'uploaded';
+    detectedMime: string | null;
+} | {
+    outcome: 'rejected';
+    reason: string;
+    detectedMime: string | null;
+} | {
+    outcome: 'expired';
+    reason: string;
+};
+/**
+ * Decide what should happen to a `requested` files row, from its object's bytes.
+ *
+ * A missing object is `expired` rather than `rejected`: nothing was uploaded, so
+ * there is nothing to reject, and the row's own retry/expiry budget governs how
+ * long the client has left. An empty object, by contrast, *was* written and is
+ * not a file.
+ */
+export declare function confirmUploadedBytes(input: ConfirmUploadInput): Promise<ConfirmUploadVerdict>;

package/esm/confirm-upload.js

@@ -0,0 +1,66 @@
+/**
+ * The byte-validating half of the presigned lane's confirmation.
+ *
+ * A presigned upload's bytes never pass through the server: the client PUTs them
+ * straight to S3, so at the moment the files row is written the only statements
+ * about the file are the client's own. `requested` is exactly that state — a
+ * claim — and the row must not reach `uploaded` until the bytes behind it have
+ * been looked at, because every downstream processing step (image versions,
+ * extraction, embeddings) fires on `uploaded` and would otherwise be handed
+ * whatever the client chose to upload.
+ *
+ * So confirmation answers three questions in order, and each has a distinct
+ * outcome on the row:
+ *
+ *   1. did the bytes arrive?          no  → `expired`  (the client walked away)
+ *   2. are they the file they claim?   no  → `rejected` (and the object deleted)
+ *   3. otherwise                           → `uploaded`
+ *
+ * The bytes are read with a ranged GET of the leading bytes, not downloaded: a
+ * magic-byte signature is in the first few dozen bytes, so this costs the same
+ * for a 2GB video as for an icon.
+ *
+ * This module is the decision, not the transition. The worker that owns the
+ * `storage:confirm_upload` job applies it by calling the generated
+ * `<files>_confirm_uploaded` / `_reject_file` / `_expire_file` functions — the
+ * verdict is returned rather than executed so that the same rule can be applied
+ * by any transport, and tested without a database.
+ */
+import { detectFromBuffer } from 'mime-bytes';
+import { checkTypeAgreement } from 'mime-bytes';
+import { readObjectPrefix } from './s3-signer';
+/**
+ * How many leading bytes to read. Signatures are far shorter than this; the
+ * margin covers formats whose signature sits at an offset (e.g. the `ftyp` box
+ * of an MP4) and gives charset detection enough text to work with.
+ */
+export const CONFIRM_PREFIX_BYTES = 4096;
+/**
+ * Decide what should happen to a `requested` files row, from its object's bytes.
+ *
+ * A missing object is `expired` rather than `rejected`: nothing was uploaded, so
+ * there is nothing to reject, and the row's own retry/expiry budget governs how
+ * long the client has left. An empty object, by contrast, *was* written and is
+ * not a file.
+ */
+export async function confirmUploadedBytes(input) {
+    const { s3, key, declaredMime, filename } = input;
+    const prefix = await readObjectPrefix(s3, key, CONFIRM_PREFIX_BYTES);
+    if (prefix === null) {
+        return { outcome: 'expired', reason: `no object at key ${key}: the upload never arrived` };
+    }
+    if (prefix.length === 0) {
+        return {
+            outcome: 'rejected',
+            reason: `object at key ${key} is empty; an upload must carry at least one byte`,
+            detectedMime: null,
+        };
+    }
+    const detected = await detectFromBuffer(prefix);
+    const detectedMime = detected?.mimeType ?? null;
+    const agreement = checkTypeAgreement({ filename, declaredMime, detectedMime });
+    if (!agreement.ok) {
+        return { outcome: 'rejected', reason: agreement.violation.message, detectedMime };
+    }
+    return { outcome: 'uploaded', detectedMime };
+}

package/esm/default-bucket.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+/**
+ * The resolved bucket coordinate.
+ *
+ * `physicalName` is the recorded S3 bucket name, or null when the logical
+ * bucket has never been provisioned — the caller mints and records it then.
+ */
+export interface ResolvedBucketCoordinate {
+    bucketId: string;
+    resolvedKey: string;
+    bucketType: 'public' | 'private' | 'temp';
+    physicalName: string | null;
+}
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+export declare function resolveDefaultBucket(pgClient: {
+    query: (opts: {
+        text: string;
+        values?: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, databaseId: string, scope: string, entityId: string | null, publicAccess: boolean, bucketKey: string | null): Promise<ResolvedBucketCoordinate>;

package/esm/default-bucket.js

@@ -0,0 +1,48 @@
+/**
+ * Server-side bucket resolution.
+ *
+ * Which bucket a write lands in belongs to the database, never to the client and
+ * never to the server's environment: a client-chosen key means a different
+ * bucket per tenant, and an env-level bucket name means storage that belongs to
+ * no tenant at all. `function_resolution.resolve_default_bucket` is the one
+ * place that answers it — a logical key when the field declares one, otherwise
+ * the reserved default tag for the requested access ('default' / 'default-public').
+ *
+ * Zero matches and several matches both raise inside SQL, so there is nothing to
+ * guess here: this module only carries the question in and the coordinate out.
+ */
+import { Logger } from '@pgpmjs/logger';
+const log = new Logger('graphile-presigned-url:default-bucket');
+const RESOLVE_DEFAULT_BUCKET_QUERY = `
+  SELECT bucket_id, resolved_key, bucket_type, physical_name
+  FROM function_resolution.resolve_default_bucket($1, $2, $3, $4, $5)
+`;
+/**
+ * Resolve the bucket a write should land in.
+ *
+ * @param scope - The storage module's scope ('app' for database-wide storage)
+ * @param entityId - The owning entity row for an entity-scoped module, else null
+ * @param publicAccess - Which reserved default tag to use when no key is named,
+ *   and an assertion on the named bucket's type when one is
+ * @param bucketKey - The field's declared logical key, or null for the default
+ */
+export async function resolveDefaultBucket(pgClient, databaseId, scope, entityId, publicAccess, bucketKey) {
+    const result = await pgClient.query({
+        text: RESOLVE_DEFAULT_BUCKET_QUERY,
+        values: [databaseId, scope, entityId, publicAccess, bucketKey],
+    });
+    const row = result.rows[0];
+    if (!row) {
+        // resolve_default_bucket raises on zero and on several matches, so an empty
+        // result means the function did not run as declared rather than "no bucket".
+        throw new Error(`STORAGE_DEFAULT_BUCKET_NO_ROW: resolve_default_bucket returned no row for ` +
+            `database=${databaseId} scope=${scope} public=${publicAccess} key=${bucketKey ?? '<default tag>'}`);
+    }
+    log.debug(`Resolved bucket ${row.resolved_key} (${row.bucket_type}) for database=${databaseId} scope=${scope}`);
+    return {
+        bucketId: row.bucket_id,
+        resolvedKey: row.resolved_key,
+        bucketType: row.bucket_type,
+        physicalName: row.physical_name,
+    };
+}

package/esm/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/esm/file-ref-registry.js

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ */
+import { Logger } from '@pgpmjs/logger';
+import { LRUCache } from 'lru-cache';
+const log = new 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 LRUCache({
+    max: 500,
+    ttl: process.env.NODE_ENV === 'development' ? FIVE_MINUTES_MS : ONE_HOUR_MS,
+    updateAgeOnGet: true,
+});
+export 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';
+    }
+}
+/**
+ * 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 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.
+ */
+export function clearFileRefFieldCache() {
+    bindingCache.clear();
+}

package/esm/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';

package/esm/index.js

@@ -26,8 +26,14 @@
  * };
  * ```
  */
+export { CONFIRM_PREFIX_BYTES, confirmUploadedBytes, } from './confirm-upload';
+export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
+export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
+export { assertUploadAllowedByBucket, buildFileProjection, finalizeStagedUpload, 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 { 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';