uploaderkit 1.0.0 → 2.0.0

package/dist/index.d.cts

@@ -1,166 +1,5 @@
-/**
- * Every type in this file must be usable from a browser and from a server.
- * That is what lets one scope definition drive the client's guards and the
- * server's guards without the two drifting apart.
- */
-type ImageExtension = 'png' | 'jpg' | 'jpeg' | 'svg' | 'webp' | 'gif' | 'ico' | 'heic';
-type CertificateExtension = 'cer' | 'crt' | 'pem';
-type KeyExtension = 'key';
-type DocumentExtension = 'pdf' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'csv' | 'txt';
-type DataExtension = 'xml' | 'json';
-type VideoExtension = 'mp4' | 'mov' | 'avi' | 'webm';
-type AudioExtension = 'mp3' | 'wav' | 'ogg' | 'aac';
-type FileExtension = ImageExtension | CertificateExtension | KeyExtension | DocumentExtension | DataExtension | VideoExtension | AudioExtension;
-/** Validation preset. Picks extensions, size ceiling and header checking. */
-type FileCategory = 'image' | 'certificate' | 'key' | 'pdf' | 'document' | 'data' | 'video' | 'audio' | 'any';
-type FileCategoryConfig = {
-    extensions: FileExtension[];
-    maxBytes: number;
-    /** Read the leading bytes to catch an .exe renamed to .pdf. */
-    validateMagicNumbers: boolean;
-    /** Lower-case singular noun used in error messages. */
-    label: string;
-    /** Value for an `<input accept="…">`. */
-    accept: string;
-};
-/**
- * The subset of the DOM `File` this package needs. A browser `File`, a Node 18+
- * `File` and a multer memory file (via `fromMulterFile`) all satisfy it, so
- * `validateFile` is the same call on both sides of the wire.
- */
-type FileLike = {
-    name: string;
-    size: number;
-    /** MIME type as reported by the source. Never trusted on its own. */
-    type: string;
-    arrayBuffer(): Promise<ArrayBuffer>;
-};
-type UploadStatus = 'idle' | 'validating' | 'uploading' | 'success' | 'error';
-/** Machine-readable reason a file was rejected. Pair with `message` for UI. */
-type ValidationCode = 'extension-not-allowed' | 'too-large' | 'empty-file' | 'magic-number-mismatch' | 'mime-not-allowed' | 'custom';
-type ValidationResult = {
-    valid: true;
-} | {
-    valid: false;
-    code: ValidationCode;
-    message: string;
-};
-type ValidationOptions = {
-    maxBytes?: number;
-    allowedExtensions?: FileExtension[];
-    validateMagicNumbers?: boolean;
-    /** Runs last, only when every built-in check passed. */
-    customValidation?: (file: FileLike) => Promise<ValidationResult>;
-};
-/**
- * Public files are served straight from their URL; private files are only ever
- * reachable through a signed, expiring URL minted by the server.
- */
-type Visibility = 'public' | 'private';
-/** Client-side image pipeline applied before upload. */
-type CompressOptions = {
-    maxWidth?: number;
-    maxHeight?: number;
-    /** 0–1. Ignored by formats without lossy encoding. */
-    quality?: number;
-    /**
-     * Drop EXIF metadata. Defaults to true: camera photos carry GPS
-     * coordinates, and a public bucket is the wrong place for them.
-     */
-    stripExif?: boolean;
-};
-/**
- * A named destination. The single source of truth for where a file lands, who
- * may read it, and what is accepted there.
- */
-type ScopeConfig = {
-    /**
-     * Storage key for an upload. Receives the owning entity and the incoming
-     * file so the caller controls collisions and folder shape.
-     */
-    path: (entityId: string, file: FileLike) => string;
-    visibility: Visibility;
-    /** Extensions accepted here. Narrower than the category preset, never wider. */
-    accept: FileExtension[];
-    maxBytes: number;
-    category?: FileCategory;
-    /** Hand the bytes to the app's cipher before they leave the server. */
-    encrypt?: boolean;
-    compress?: CompressOptions;
-    /** Replace the object at the same key instead of adding a new one. */
-    overwrite?: boolean;
-    /** Documentation-only today; drives lifecycle rules once adapters read it. */
-    retention?: string;
-    /** Free-form tags forwarded to the provider when it supports metadata. */
-    metadata?: Record<string, string>;
-};
-type ScopeRegistry<T extends Record<string, ScopeConfig>> = {
-    scopes: T;
-    names: (keyof T & string)[];
-    get(name: string): ScopeConfig;
-    has(name: string): boolean;
-    /** `<input accept>` string for a scope, derived from its extensions. */
-    accept(name: keyof T & string): string;
-};
-/** What the app persists after a successful upload. */
-type StoredFile = {
-    /** Provider key. The handle for delete, re-sign and download. */
-    key: string;
-    /** Public URL, or a signed expiring URL when the scope is private. */
-    url: string;
-    scope: string;
-    entityId: string;
-    fileName: string;
-    mimeType: string;
-    size: number;
-    /** Enables dedupe and integrity checks when the provider reports it. */
-    checksum?: string;
-    uploadedAt: number;
-    uploadedBy?: string;
-};
-type PutInput = {
-    key: string;
-    body: Uint8Array;
-    contentType: string;
-    visibility: Visibility;
-    metadata?: Record<string, string>;
-};
-/**
- * What a provider can actually do. Declared rather than discovered so a scope
- * that needs signed URLs fails at boot, not the first time a user opens a file.
- */
-type ProviderCapabilities = {
-    signedUrl: boolean;
-    resumable: boolean;
-    rangeRead: boolean;
-};
-type SignedUrlOptions = {
-    /** Seconds until the URL stops working. */
-    expiresIn: number;
-    /** Force a download instead of inline rendering. */
-    download?: boolean;
-};
-type StorageProvider = {
-    name: string;
-    capabilities: ProviderCapabilities;
-    put(input: PutInput): Promise<{
-        key: string;
-        url: string;
-        checksum?: string;
-    }>;
-    get(key: string): Promise<Uint8Array>;
-    delete(key: string): Promise<boolean>;
-    signedUrl?(key: string, options: SignedUrlOptions): Promise<string>;
-    list(prefix: string): Promise<{
-        key: string;
-        size: number;
-    }[]>;
-};
-/** Injected cipher for `encrypt: true` scopes. The package never ships one. */
-type CryptoHooks = {
-    encrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-    decrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-};
+import { F as FileCategory, a as FileCategoryConfig, b as FileExtension, c as FileLike, d as ScopeConfig, e as ScopeRegistry, S as StorageProvider, R as ReplaceMode, U as UploaderLabels, f as ValidationResult, g as ValidationOptions } from './types-BSlJJwti.cjs';
+export { A as AudioExtension, C as CertificateExtension, h as CompressOptions, i as CryptoHooks, D as DEFAULT_LABELS, j as DataExtension, k as DocumentExtension, E as EN_LABELS, l as ES_LABELS, I as ImageExtension, K as KeyExtension, P as ProviderCapabilities, m as PutInput, n as SignedUrlOptions, o as StoredFile, p as UploadStatus, q as ValidationCode, r as VideoExtension, V as Visibility, s as resolveLabels } from './types-BSlJJwti.cjs';
 
 declare const KB = 1024;
 declare const MB: number;
@@ -183,6 +22,30 @@ declare const getFileExtension: (fileName: string) => string;
 declare const getMimeType: (fileName: string) => string;
 declare const isKnownExtension: (value: string) => value is FileExtension;
 declare const formatFileSize: (bytes: number) => string;
+/**
+ * Turns a user's file name into a safe key segment: ASCII, lower case, one
+ * extension, no path syntax.
+ *
+ * Call it INSIDE your scope's `path()`, not around it:
+ *
+ * ```ts
+ * path: (id, file) => `Docs/${id}/${sanitizeFileName(file.name)}`
+ * ```
+ *
+ * `resolveKey` deliberately does not apply it for you. It would rewrite the key
+ * your `path()` returned, and a client computing the same key to decide replace
+ * mode would then disagree with the server. Inside `path()` both sides run the
+ * one function and cannot drift.
+ *
+ * This exists because a macOS screenshot took an API down. `Screenshot
+ * 2026-08-31 at 4.18.54 p.m..png` ends in `p.m.` + `.png`, so the raw name
+ * carries `..`; the traversal guard rejected the key and the consumer dropped
+ * the rejection, killing the process.
+ *
+ * Only the KEY is slugged — keep the original in `StoredFile.fileName`, which
+ * is what a UI should render.
+ */
+declare const sanitizeFileName: (fileName: string) => string;
 /** Value for an `<input accept="…">` built from an extension list. */
 declare const toAcceptAttribute: (extensions: FileExtension[]) => string;
 /**
@@ -200,36 +63,60 @@ declare const fromMulterFile: (file: {
 declare class ScopeError extends Error {
     name: string;
 }
+/** True when `path` returns the same key whatever the file is called. */
+declare const hasStableKey: (scope: ScopeConfig) => boolean;
+/**
+ * The mode a scope runs in when it does not name one.
+ *
+ * @see AGENTS.md §3 — why a stable key needs no sweep and a name-carrying one does
+ */
+declare const resolveReplaceMode: (scope: ScopeConfig) => ReplaceMode;
+/** Folder an `'entity'` replace is allowed to sweep. */
+declare const resolveScopePrefix: (scope: ScopeConfig, entityId: string) => string;
 /**
  * Declares every destination an app can write to. The returned registry is
  * imported by the client (to configure inputs and pre-validate) and by the
  * server (to authorize and re-validate), which is what keeps the two in sync.
  *
  * Definitions are checked eagerly: a malformed scope throws at import time,
- * not on the first upload.
+ * not on the first upload. That includes the two replace mistakes no runtime
+ * check could recover from — an entity-wide replace on a collection, and two
+ * scopes whose folders overlap, where an avatar upload would delete the same
+ * user's documents.
  */
 declare const defineScopes: <T extends Record<string, ScopeConfig>>(scopes: T) => ScopeRegistry<T>;
 /**
  * The one validation call. Client runs it for feedback, server runs it for
  * safety, both against the same scope.
+ *
+ * `labels` is what keeps the two answers identical in wording as well as in
+ * verdict: the hook passes the copy it renders with, `createStorage` passes
+ * the copy it was configured with.
  */
-declare const validateForScope: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, file: FileLike) => Promise<ValidationResult>;
+declare const validateForScope: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, file: FileLike, labels?: Partial<UploaderLabels>) => Promise<ValidationResult>;
 /**
  * Fails fast when a provider cannot honour what the scopes promise — a private
  * scope on a provider that cannot sign URLs is a runtime 403 waiting to happen.
  */
 declare const assertProviderSupports: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, provider: StorageProvider) => void;
-/** Resolves the storage key for an upload. */
+/**
+ * Resolves the storage key for an upload.
+ *
+ * The guard is a backstop, not a sanitizer: it refuses a key rather than
+ * rewriting one, because a client computing the same key to decide replace
+ * mode would then disagree with the server. Run {@link sanitizeFileName}
+ * inside the scope's `path()` and both sides stay identical.
+ */
 declare const resolveKey: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, entityId: string, file: FileLike) => string;
 
-declare const validateExtension: (fileName: string, allowed: FileExtension[]) => ValidationResult;
-declare const validateSize: (size: number, maxBytes: number) => ValidationResult;
+declare const validateExtension: (fileName: string, allowed: FileExtension[], labels?: Partial<UploaderLabels>) => ValidationResult;
+declare const validateSize: (size: number, maxBytes: number, labels?: Partial<UploaderLabels>) => ValidationResult;
 /**
  * Compares the file's leading bytes against the signature its extension
  * claims. Extensions without a known signature pass — absence of a signature
  * is not evidence of tampering.
  */
-declare const validateMagicNumbers: (file: FileLike) => Promise<ValidationResult>;
+declare const validateMagicNumbers: (file: FileLike, labels?: Partial<UploaderLabels>) => Promise<ValidationResult>;
 /**
  * Runs the checks cheapest-first so a 2 GB file is rejected on its size before
  * anything reads its bytes.
@@ -242,4 +129,4 @@ type FileValidation = {
 /** Validates every file and reports each result; never short-circuits. */
 declare const validateFiles: (files: FileLike[], options?: ValidationOptions) => Promise<FileValidation[]>;
 
-export { type AudioExtension, type CertificateExtension, type CompressOptions, type CryptoHooks, type DataExtension, type DocumentExtension, FILE_CATEGORY_CONFIG, type FileCategory, type FileCategoryConfig, type FileExtension, type FileLike, type FileValidation, GB, type ImageExtension, KB, type KeyExtension, MAGIC_NUMBERS, MB, MIME_TYPES, type ProviderCapabilities, type PutInput, type ScopeConfig, ScopeError, type ScopeRegistry, type SignedUrlOptions, type StorageProvider, type StoredFile, type UploadStatus, type ValidationCode, type ValidationOptions, type ValidationResult, type VideoExtension, type Visibility, assertProviderSupports, defineScopes, formatFileSize, fromMulterFile, getFileExtension, getMimeType, isKnownExtension, resolveKey, toAcceptAttribute, validateExtension, validateFile, validateFiles, validateForScope, validateMagicNumbers, validateSize };
+export { FILE_CATEGORY_CONFIG, FileCategory, FileCategoryConfig, FileExtension, FileLike, type FileValidation, GB, KB, MAGIC_NUMBERS, MB, MIME_TYPES, ReplaceMode, ScopeConfig, ScopeError, ScopeRegistry, StorageProvider, UploaderLabels, ValidationOptions, ValidationResult, assertProviderSupports, defineScopes, formatFileSize, fromMulterFile, getFileExtension, getMimeType, hasStableKey, isKnownExtension, resolveKey, resolveReplaceMode, resolveScopePrefix, sanitizeFileName, toAcceptAttribute, validateExtension, validateFile, validateFiles, validateForScope, validateMagicNumbers, validateSize };

package/dist/index.d.ts

@@ -1,166 +1,5 @@
-/**
- * Every type in this file must be usable from a browser and from a server.
- * That is what lets one scope definition drive the client's guards and the
- * server's guards without the two drifting apart.
- */
-type ImageExtension = 'png' | 'jpg' | 'jpeg' | 'svg' | 'webp' | 'gif' | 'ico' | 'heic';
-type CertificateExtension = 'cer' | 'crt' | 'pem';
-type KeyExtension = 'key';
-type DocumentExtension = 'pdf' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'csv' | 'txt';
-type DataExtension = 'xml' | 'json';
-type VideoExtension = 'mp4' | 'mov' | 'avi' | 'webm';
-type AudioExtension = 'mp3' | 'wav' | 'ogg' | 'aac';
-type FileExtension = ImageExtension | CertificateExtension | KeyExtension | DocumentExtension | DataExtension | VideoExtension | AudioExtension;
-/** Validation preset. Picks extensions, size ceiling and header checking. */
-type FileCategory = 'image' | 'certificate' | 'key' | 'pdf' | 'document' | 'data' | 'video' | 'audio' | 'any';
-type FileCategoryConfig = {
-    extensions: FileExtension[];
-    maxBytes: number;
-    /** Read the leading bytes to catch an .exe renamed to .pdf. */
-    validateMagicNumbers: boolean;
-    /** Lower-case singular noun used in error messages. */
-    label: string;
-    /** Value for an `<input accept="…">`. */
-    accept: string;
-};
-/**
- * The subset of the DOM `File` this package needs. A browser `File`, a Node 18+
- * `File` and a multer memory file (via `fromMulterFile`) all satisfy it, so
- * `validateFile` is the same call on both sides of the wire.
- */
-type FileLike = {
-    name: string;
-    size: number;
-    /** MIME type as reported by the source. Never trusted on its own. */
-    type: string;
-    arrayBuffer(): Promise<ArrayBuffer>;
-};
-type UploadStatus = 'idle' | 'validating' | 'uploading' | 'success' | 'error';
-/** Machine-readable reason a file was rejected. Pair with `message` for UI. */
-type ValidationCode = 'extension-not-allowed' | 'too-large' | 'empty-file' | 'magic-number-mismatch' | 'mime-not-allowed' | 'custom';
-type ValidationResult = {
-    valid: true;
-} | {
-    valid: false;
-    code: ValidationCode;
-    message: string;
-};
-type ValidationOptions = {
-    maxBytes?: number;
-    allowedExtensions?: FileExtension[];
-    validateMagicNumbers?: boolean;
-    /** Runs last, only when every built-in check passed. */
-    customValidation?: (file: FileLike) => Promise<ValidationResult>;
-};
-/**
- * Public files are served straight from their URL; private files are only ever
- * reachable through a signed, expiring URL minted by the server.
- */
-type Visibility = 'public' | 'private';
-/** Client-side image pipeline applied before upload. */
-type CompressOptions = {
-    maxWidth?: number;
-    maxHeight?: number;
-    /** 0–1. Ignored by formats without lossy encoding. */
-    quality?: number;
-    /**
-     * Drop EXIF metadata. Defaults to true: camera photos carry GPS
-     * coordinates, and a public bucket is the wrong place for them.
-     */
-    stripExif?: boolean;
-};
-/**
- * A named destination. The single source of truth for where a file lands, who
- * may read it, and what is accepted there.
- */
-type ScopeConfig = {
-    /**
-     * Storage key for an upload. Receives the owning entity and the incoming
-     * file so the caller controls collisions and folder shape.
-     */
-    path: (entityId: string, file: FileLike) => string;
-    visibility: Visibility;
-    /** Extensions accepted here. Narrower than the category preset, never wider. */
-    accept: FileExtension[];
-    maxBytes: number;
-    category?: FileCategory;
-    /** Hand the bytes to the app's cipher before they leave the server. */
-    encrypt?: boolean;
-    compress?: CompressOptions;
-    /** Replace the object at the same key instead of adding a new one. */
-    overwrite?: boolean;
-    /** Documentation-only today; drives lifecycle rules once adapters read it. */
-    retention?: string;
-    /** Free-form tags forwarded to the provider when it supports metadata. */
-    metadata?: Record<string, string>;
-};
-type ScopeRegistry<T extends Record<string, ScopeConfig>> = {
-    scopes: T;
-    names: (keyof T & string)[];
-    get(name: string): ScopeConfig;
-    has(name: string): boolean;
-    /** `<input accept>` string for a scope, derived from its extensions. */
-    accept(name: keyof T & string): string;
-};
-/** What the app persists after a successful upload. */
-type StoredFile = {
-    /** Provider key. The handle for delete, re-sign and download. */
-    key: string;
-    /** Public URL, or a signed expiring URL when the scope is private. */
-    url: string;
-    scope: string;
-    entityId: string;
-    fileName: string;
-    mimeType: string;
-    size: number;
-    /** Enables dedupe and integrity checks when the provider reports it. */
-    checksum?: string;
-    uploadedAt: number;
-    uploadedBy?: string;
-};
-type PutInput = {
-    key: string;
-    body: Uint8Array;
-    contentType: string;
-    visibility: Visibility;
-    metadata?: Record<string, string>;
-};
-/**
- * What a provider can actually do. Declared rather than discovered so a scope
- * that needs signed URLs fails at boot, not the first time a user opens a file.
- */
-type ProviderCapabilities = {
-    signedUrl: boolean;
-    resumable: boolean;
-    rangeRead: boolean;
-};
-type SignedUrlOptions = {
-    /** Seconds until the URL stops working. */
-    expiresIn: number;
-    /** Force a download instead of inline rendering. */
-    download?: boolean;
-};
-type StorageProvider = {
-    name: string;
-    capabilities: ProviderCapabilities;
-    put(input: PutInput): Promise<{
-        key: string;
-        url: string;
-        checksum?: string;
-    }>;
-    get(key: string): Promise<Uint8Array>;
-    delete(key: string): Promise<boolean>;
-    signedUrl?(key: string, options: SignedUrlOptions): Promise<string>;
-    list(prefix: string): Promise<{
-        key: string;
-        size: number;
-    }[]>;
-};
-/** Injected cipher for `encrypt: true` scopes. The package never ships one. */
-type CryptoHooks = {
-    encrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-    decrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-};
+import { F as FileCategory, a as FileCategoryConfig, b as FileExtension, c as FileLike, d as ScopeConfig, e as ScopeRegistry, S as StorageProvider, R as ReplaceMode, U as UploaderLabels, f as ValidationResult, g as ValidationOptions } from './types-BSlJJwti.js';
+export { A as AudioExtension, C as CertificateExtension, h as CompressOptions, i as CryptoHooks, D as DEFAULT_LABELS, j as DataExtension, k as DocumentExtension, E as EN_LABELS, l as ES_LABELS, I as ImageExtension, K as KeyExtension, P as ProviderCapabilities, m as PutInput, n as SignedUrlOptions, o as StoredFile, p as UploadStatus, q as ValidationCode, r as VideoExtension, V as Visibility, s as resolveLabels } from './types-BSlJJwti.js';
 
 declare const KB = 1024;
 declare const MB: number;
@@ -183,6 +22,30 @@ declare const getFileExtension: (fileName: string) => string;
 declare const getMimeType: (fileName: string) => string;
 declare const isKnownExtension: (value: string) => value is FileExtension;
 declare const formatFileSize: (bytes: number) => string;
+/**
+ * Turns a user's file name into a safe key segment: ASCII, lower case, one
+ * extension, no path syntax.
+ *
+ * Call it INSIDE your scope's `path()`, not around it:
+ *
+ * ```ts
+ * path: (id, file) => `Docs/${id}/${sanitizeFileName(file.name)}`
+ * ```
+ *
+ * `resolveKey` deliberately does not apply it for you. It would rewrite the key
+ * your `path()` returned, and a client computing the same key to decide replace
+ * mode would then disagree with the server. Inside `path()` both sides run the
+ * one function and cannot drift.
+ *
+ * This exists because a macOS screenshot took an API down. `Screenshot
+ * 2026-08-31 at 4.18.54 p.m..png` ends in `p.m.` + `.png`, so the raw name
+ * carries `..`; the traversal guard rejected the key and the consumer dropped
+ * the rejection, killing the process.
+ *
+ * Only the KEY is slugged — keep the original in `StoredFile.fileName`, which
+ * is what a UI should render.
+ */
+declare const sanitizeFileName: (fileName: string) => string;
 /** Value for an `<input accept="…">` built from an extension list. */
 declare const toAcceptAttribute: (extensions: FileExtension[]) => string;
 /**
@@ -200,36 +63,60 @@ declare const fromMulterFile: (file: {
 declare class ScopeError extends Error {
     name: string;
 }
+/** True when `path` returns the same key whatever the file is called. */
+declare const hasStableKey: (scope: ScopeConfig) => boolean;
+/**
+ * The mode a scope runs in when it does not name one.
+ *
+ * @see AGENTS.md §3 — why a stable key needs no sweep and a name-carrying one does
+ */
+declare const resolveReplaceMode: (scope: ScopeConfig) => ReplaceMode;
+/** Folder an `'entity'` replace is allowed to sweep. */
+declare const resolveScopePrefix: (scope: ScopeConfig, entityId: string) => string;
 /**
  * Declares every destination an app can write to. The returned registry is
  * imported by the client (to configure inputs and pre-validate) and by the
  * server (to authorize and re-validate), which is what keeps the two in sync.
  *
  * Definitions are checked eagerly: a malformed scope throws at import time,
- * not on the first upload.
+ * not on the first upload. That includes the two replace mistakes no runtime
+ * check could recover from — an entity-wide replace on a collection, and two
+ * scopes whose folders overlap, where an avatar upload would delete the same
+ * user's documents.
  */
 declare const defineScopes: <T extends Record<string, ScopeConfig>>(scopes: T) => ScopeRegistry<T>;
 /**
  * The one validation call. Client runs it for feedback, server runs it for
  * safety, both against the same scope.
+ *
+ * `labels` is what keeps the two answers identical in wording as well as in
+ * verdict: the hook passes the copy it renders with, `createStorage` passes
+ * the copy it was configured with.
  */
-declare const validateForScope: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, file: FileLike) => Promise<ValidationResult>;
+declare const validateForScope: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, file: FileLike, labels?: Partial<UploaderLabels>) => Promise<ValidationResult>;
 /**
  * Fails fast when a provider cannot honour what the scopes promise — a private
  * scope on a provider that cannot sign URLs is a runtime 403 waiting to happen.
  */
 declare const assertProviderSupports: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, provider: StorageProvider) => void;
-/** Resolves the storage key for an upload. */
+/**
+ * Resolves the storage key for an upload.
+ *
+ * The guard is a backstop, not a sanitizer: it refuses a key rather than
+ * rewriting one, because a client computing the same key to decide replace
+ * mode would then disagree with the server. Run {@link sanitizeFileName}
+ * inside the scope's `path()` and both sides stay identical.
+ */
 declare const resolveKey: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, entityId: string, file: FileLike) => string;
 
-declare const validateExtension: (fileName: string, allowed: FileExtension[]) => ValidationResult;
-declare const validateSize: (size: number, maxBytes: number) => ValidationResult;
+declare const validateExtension: (fileName: string, allowed: FileExtension[], labels?: Partial<UploaderLabels>) => ValidationResult;
+declare const validateSize: (size: number, maxBytes: number, labels?: Partial<UploaderLabels>) => ValidationResult;
 /**
  * Compares the file's leading bytes against the signature its extension
  * claims. Extensions without a known signature pass — absence of a signature
  * is not evidence of tampering.
  */
-declare const validateMagicNumbers: (file: FileLike) => Promise<ValidationResult>;
+declare const validateMagicNumbers: (file: FileLike, labels?: Partial<UploaderLabels>) => Promise<ValidationResult>;
 /**
  * Runs the checks cheapest-first so a 2 GB file is rejected on its size before
  * anything reads its bytes.
@@ -242,4 +129,4 @@ type FileValidation = {
 /** Validates every file and reports each result; never short-circuits. */
 declare const validateFiles: (files: FileLike[], options?: ValidationOptions) => Promise<FileValidation[]>;
 
-export { type AudioExtension, type CertificateExtension, type CompressOptions, type CryptoHooks, type DataExtension, type DocumentExtension, FILE_CATEGORY_CONFIG, type FileCategory, type FileCategoryConfig, type FileExtension, type FileLike, type FileValidation, GB, type ImageExtension, KB, type KeyExtension, MAGIC_NUMBERS, MB, MIME_TYPES, type ProviderCapabilities, type PutInput, type ScopeConfig, ScopeError, type ScopeRegistry, type SignedUrlOptions, type StorageProvider, type StoredFile, type UploadStatus, type ValidationCode, type ValidationOptions, type ValidationResult, type VideoExtension, type Visibility, assertProviderSupports, defineScopes, formatFileSize, fromMulterFile, getFileExtension, getMimeType, isKnownExtension, resolveKey, toAcceptAttribute, validateExtension, validateFile, validateFiles, validateForScope, validateMagicNumbers, validateSize };
+export { FILE_CATEGORY_CONFIG, FileCategory, FileCategoryConfig, FileExtension, FileLike, type FileValidation, GB, KB, MAGIC_NUMBERS, MB, MIME_TYPES, ReplaceMode, ScopeConfig, ScopeError, ScopeRegistry, StorageProvider, UploaderLabels, ValidationOptions, ValidationResult, assertProviderSupports, defineScopes, formatFileSize, fromMulterFile, getFileExtension, getMimeType, hasStableKey, isKnownExtension, resolveKey, resolveReplaceMode, resolveScopePrefix, sanitizeFileName, toAcceptAttribute, validateExtension, validateFile, validateFiles, validateForScope, validateMagicNumbers, validateSize };