alepha 0.21.1 → 0.22.0

package/dist/api/files/index.d.ts

@@ -1,37 +1,32 @@
-import * as _$alepha from "alepha";
 import { Alepha, FileLike, Static, TNull, TObject, TOptional, TSchema, TUnion } from "alepha";
 import { BucketPrimitive } from "alepha/bucket";
 import { UserAccountToken } from "alepha/security";
-import * as _$alepha_server0 from "alepha/server";
 import { Ok } from "alepha/server";
 import { DateTime, DateTimeProvider, DurationLike } from "alepha/datetime";
-import * as _$alepha_logger0 from "alepha/logger";
-import * as _$alepha_orm0 from "alepha/orm";
-import { Page } from "alepha/orm";
-import * as _$alepha_scheduler0 from "alepha/scheduler";
-import * as _$typebox from "typebox";
+import { Page, RepositoryProvider } from "alepha/orm";
+import { FileSystemProvider } from "alepha/system";
 import { BuildExtraConfigColumns, SQL } from "drizzle-orm";
 import { PgColumnBuilderBase, PgSequenceOptions, PgTableExtraConfigValue, UpdateDeleteAction } from "drizzle-orm/pg-core";
 //#region ../../src/api/files/entities/files.d.ts
-declare const files: _$alepha_orm0.EntityPrimitive<_$typebox.TObject<{
-  id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
-  version: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TInteger, typeof _$alepha_orm0.PG_VERSION>, typeof _$alepha_orm0.PG_DEFAULT>;
-  createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
-  updatedAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_UPDATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
-  organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
-  blobId: _$typebox.TString;
-  creator: _$typebox.TOptional<_$typebox.TString>;
-  creatorRealm: _$typebox.TOptional<_$typebox.TString>;
-  creatorName: _$typebox.TOptional<_$typebox.TString>;
-  bucket: _$typebox.TString;
-  expirationDate: _$typebox.TOptional<_$typebox.TString>;
+declare const files: import("alepha/orm").EntityPrimitive<import("typebox").TObject<{
+  id: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_PRIMARY_KEY>, typeof import("alepha/orm").PG_DEFAULT>;
+  version: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TInteger, typeof import("alepha/orm").PG_VERSION>, typeof import("alepha/orm").PG_DEFAULT>;
+  createdAt: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_CREATED_AT>, typeof import("alepha/orm").PG_DEFAULT>;
+  updatedAt: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_UPDATED_AT>, typeof import("alepha/orm").PG_DEFAULT>;
+  organizationId: import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_ORGANIZATION>;
+  blobId: import("typebox").TString;
+  creator: import("typebox").TOptional<import("typebox").TString>;
+  creatorRealm: import("typebox").TOptional<import("typebox").TString>;
+  creatorName: import("typebox").TOptional<import("typebox").TString>;
+  bucket: import("typebox").TString;
+  expirationDate: import("typebox").TOptional<import("typebox").TString>;
   /**
    * Display name. Mutable via `FileService.updateFile` — can be renamed
    * by callers (e.g. an Archive UI letting users rename uploaded blobs).
    * Initialized to the uploader's filename at upload time. Use
    * `originalName` if you need the as-uploaded filename after a rename.
    */
-  name: _$typebox.TString;
+  name: import("typebox").TString;
   /**
    * Immutable record of the uploader's filename at upload time. Set once
    * by `FileService.uploadFile` and the `bucket:file:uploaded` hook;
@@ -39,37 +34,37 @@ declare const files: _$alepha_orm0.EntityPrimitive<_$typebox.TObject<{
    * headers (Content-Disposition), audit trails, and any UI that wants
    * to show "originally uploaded as X" alongside a renamed file.
    */
-  originalName: _$typebox.TOptional<_$typebox.TString>;
-  size: _$typebox.TNumber;
-  mimeType: _$typebox.TString;
+  originalName: import("typebox").TOptional<import("typebox").TString>;
+  size: import("typebox").TNumber;
+  mimeType: import("typebox").TString;
   /**
    * Free-form taxonomy. Normalized server-side (trim/lowercase/dedupe is
    * caller's responsibility for now). Use with `FileQuery.tags` to
    * filter via array-contains.
    */
-  tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
+  tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
   /**
    * SHA-256 hex digest of the file content (64 lowercase hex chars).
    * Computed at upload time by `FileService.calculateChecksum`. Stable
    * — never recomputed after upload. Use for integrity verification,
    * content-based dedup, or downstream virus-scan correlation.
    */
-  checksum: _$typebox.TOptional<_$typebox.TString>;
+  checksum: import("typebox").TOptional<import("typebox").TString>;
 }>>;
 type FileEntity = Static<typeof files.schema>;
 //#endregion
 //#region ../../src/api/files/schemas/fileQuerySchema.d.ts
-declare const fileQuerySchema: _$typebox.TObject<{
-  page: _$typebox.TOptional<_$typebox.TInteger>;
-  size: _$typebox.TOptional<_$typebox.TInteger>;
-  sort: _$typebox.TOptional<_$typebox.TString>;
-  bucket: _$typebox.TOptional<_$typebox.TString>;
-  tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-  name: _$typebox.TOptional<_$typebox.TString>;
-  mimeType: _$typebox.TOptional<_$typebox.TString>;
-  creator: _$typebox.TOptional<_$typebox.TString>;
-  createdAfter: _$typebox.TOptional<_$typebox.TString>;
-  createdBefore: _$typebox.TOptional<_$typebox.TString>;
+declare const fileQuerySchema: import("typebox").TObject<{
+  page: import("typebox").TOptional<import("typebox").TInteger>;
+  size: import("typebox").TOptional<import("typebox").TInteger>;
+  sort: import("typebox").TOptional<import("typebox").TString>;
+  bucket: import("typebox").TOptional<import("typebox").TString>;
+  tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+  name: import("typebox").TOptional<import("typebox").TString>;
+  mimeType: import("typebox").TOptional<import("typebox").TString>;
+  creator: import("typebox").TOptional<import("typebox").TString>;
+  createdAfter: import("typebox").TOptional<import("typebox").TString>;
+  createdBefore: import("typebox").TOptional<import("typebox").TString>;
 }>;
 type FileQuery = Static<typeof fileQuerySchema>;
 //#endregion
@@ -364,8 +359,8 @@ type PgAttr<T extends TSchema, TAttr extends PgSymbolKeys> = T & { [K in TAttr]:
  * - `d1://BINDING_NAME` — Cloudflare D1
  * - `hyperdrive://BINDING_NAME` — Cloudflare Hyperdrive
  */
-declare const databaseEnvSchema: _$typebox.TObject<{
-  DATABASE_URL: _$typebox.TOptional<_$typebox.TString>;
+declare const databaseEnvSchema: import("typebox").TObject<{
+  DATABASE_URL: import("typebox").TOptional<import("typebox").TString>;
   /**
    * Enable or disable push-based schema synchronization (drizzle-kit push).
    *
@@ -373,55 +368,62 @@ declare const databaseEnvSchema: _$typebox.TObject<{
    * Set to `false` in development to skip automatic schema sync
    * (e.g. when managing migrations manually).
    */
-  DATABASE_SYNC: _$typebox.TOptional<_$typebox.TBoolean>;
+  DATABASE_SYNC: import("typebox").TOptional<import("typebox").TBoolean>;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof databaseEnvSchema>> {}
 } //# sourceMappingURL=databaseEnvSchema.d.ts.map
 //#endregion
 //#region ../../src/api/files/schemas/fileResourceSchema.d.ts
-declare const fileResourceSchema: _$typebox.TObject<{
-  id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
-  version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
-  createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-  updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
-  organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
-  blobId: _$typebox.TString;
-  creator: _$typebox.TOptional<_$typebox.TString>;
-  creatorRealm: _$typebox.TOptional<_$typebox.TString>;
-  creatorName: _$typebox.TOptional<_$typebox.TString>;
-  bucket: _$typebox.TString;
-  expirationDate: _$typebox.TOptional<_$typebox.TString>;
-  name: _$typebox.TString;
-  originalName: _$typebox.TOptional<_$typebox.TString>;
-  size: _$typebox.TNumber;
-  mimeType: _$typebox.TString;
-  tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-  checksum: _$typebox.TOptional<_$typebox.TString>;
+declare const fileResourceSchema: import("typebox").TObject<{
+  id: PgAttr<PgAttr<import("typebox").TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+  version: PgAttr<PgAttr<import("typebox").TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+  createdAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+  updatedAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+  organizationId: PgAttr<import("typebox").TString, typeof PG_ORGANIZATION>;
+  blobId: import("typebox").TString;
+  creator: import("typebox").TOptional<import("typebox").TString>;
+  creatorRealm: import("typebox").TOptional<import("typebox").TString>;
+  creatorName: import("typebox").TOptional<import("typebox").TString>;
+  bucket: import("typebox").TString;
+  expirationDate: import("typebox").TOptional<import("typebox").TString>;
+  name: import("typebox").TString;
+  originalName: import("typebox").TOptional<import("typebox").TString>;
+  size: import("typebox").TNumber;
+  mimeType: import("typebox").TString;
+  tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+  checksum: import("typebox").TOptional<import("typebox").TString>;
+  user: import("typebox").TOptional<import("typebox").TObject<{
+    id: import("typebox").TString;
+    email: import("typebox").TOptional<import("typebox").TString>;
+    username: import("typebox").TOptional<import("typebox").TString>;
+    firstName: import("typebox").TOptional<import("typebox").TString>;
+    lastName: import("typebox").TOptional<import("typebox").TString>;
+  }>>;
 }>;
 type FileResource = Static<typeof fileResourceSchema>;
 //#endregion
 //#region ../../src/api/files/schemas/storageStatsSchema.d.ts
-declare const bucketStatsSchema: _$typebox.TObject<{
-  bucket: _$typebox.TString;
-  totalSize: _$typebox.TNumber;
-  fileCount: _$typebox.TNumber;
+declare const bucketStatsSchema: import("typebox").TObject<{
+  bucket: import("typebox").TString;
+  totalSize: import("typebox").TNumber;
+  fileCount: import("typebox").TNumber;
 }>;
-declare const mimeTypeStatsSchema: _$typebox.TObject<{
-  mimeType: _$typebox.TString;
-  fileCount: _$typebox.TNumber;
+declare const mimeTypeStatsSchema: import("typebox").TObject<{
+  mimeType: import("typebox").TString;
+  fileCount: import("typebox").TNumber;
 }>;
-declare const storageStatsSchema: _$typebox.TObject<{
-  totalSize: _$typebox.TNumber;
-  totalFiles: _$typebox.TNumber;
-  byBucket: _$typebox.TArray<_$typebox.TObject<{
-    bucket: _$typebox.TString;
-    totalSize: _$typebox.TNumber;
-    fileCount: _$typebox.TNumber;
+declare const storageStatsSchema: import("typebox").TObject<{
+  totalSize: import("typebox").TNumber;
+  totalFiles: import("typebox").TNumber;
+  byBucket: import("typebox").TArray<import("typebox").TObject<{
+    bucket: import("typebox").TString;
+    totalSize: import("typebox").TNumber;
+    fileCount: import("typebox").TNumber;
   }>>;
-  byMimeType: _$typebox.TArray<_$typebox.TObject<{
-    mimeType: _$typebox.TString;
-    fileCount: _$typebox.TNumber;
+  byMimeType: import("typebox").TArray<import("typebox").TObject<{
+    mimeType: import("typebox").TString;
+    fileCount: import("typebox").TNumber;
   }>>;
 }>;
 type BucketStats = Static<typeof bucketStatsSchema>;
@@ -431,38 +433,74 @@ type StorageStats = Static<typeof storageStatsSchema>;
 //#region ../../src/api/files/services/FileService.d.ts
 declare class FileService {
   protected readonly alepha: Alepha;
-  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly log: import("alepha/logger").Logger;
   protected readonly dateTimeProvider: DateTimeProvider;
+  protected readonly repositoryProvider: RepositoryProvider;
+  protected readonly fileSystem: FileSystemProvider;
   protected readonly defaultBucket: BucketPrimitive;
-  readonly fileRepository: _$alepha_orm0.Repository<_$typebox.TObject<{
-    id: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_PRIMARY_KEY>, typeof _$alepha_orm0.PG_DEFAULT>;
-    version: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TInteger, typeof _$alepha_orm0.PG_VERSION>, typeof _$alepha_orm0.PG_DEFAULT>;
-    createdAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_CREATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
-    updatedAt: _$alepha_orm0.PgAttr<_$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_UPDATED_AT>, typeof _$alepha_orm0.PG_DEFAULT>;
-    organizationId: _$alepha_orm0.PgAttr<_$typebox.TString, typeof _$alepha_orm0.PG_ORGANIZATION>;
-    blobId: _$typebox.TString;
-    creator: _$typebox.TOptional<_$typebox.TString>;
-    creatorRealm: _$typebox.TOptional<_$typebox.TString>;
-    creatorName: _$typebox.TOptional<_$typebox.TString>;
-    bucket: _$typebox.TString;
-    expirationDate: _$typebox.TOptional<_$typebox.TString>;
-    name: _$typebox.TString;
-    originalName: _$typebox.TOptional<_$typebox.TString>;
-    size: _$typebox.TNumber;
-    mimeType: _$typebox.TString;
-    tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-    checksum: _$typebox.TOptional<_$typebox.TString>;
+  readonly fileRepository: import("alepha/orm").Repository<import("typebox").TObject<{
+    id: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_PRIMARY_KEY>, typeof import("alepha/orm").PG_DEFAULT>;
+    version: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TInteger, typeof import("alepha/orm").PG_VERSION>, typeof import("alepha/orm").PG_DEFAULT>;
+    createdAt: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_CREATED_AT>, typeof import("alepha/orm").PG_DEFAULT>;
+    updatedAt: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_UPDATED_AT>, typeof import("alepha/orm").PG_DEFAULT>;
+    organizationId: import("alepha/orm").PgAttr<import("typebox").TString, typeof import("alepha/orm").PG_ORGANIZATION>;
+    blobId: import("typebox").TString;
+    creator: import("typebox").TOptional<import("typebox").TString>;
+    creatorRealm: import("typebox").TOptional<import("typebox").TString>;
+    creatorName: import("typebox").TOptional<import("typebox").TString>;
+    bucket: import("typebox").TString;
+    expirationDate: import("typebox").TOptional<import("typebox").TString>;
+    name: import("typebox").TString;
+    originalName: import("typebox").TOptional<import("typebox").TString>;
+    size: import("typebox").TNumber;
+    mimeType: import("typebox").TString;
+    tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+    checksum: import("typebox").TOptional<import("typebox").TString>;
   }>>;
-  protected onUploadFile: _$alepha.HookPrimitive<"bucket:file:uploaded">;
-  protected onDeleteBucketFile: _$alepha.HookPrimitive<"bucket:file:deleted">;
+  /**
+   * Best-effort left join embedding the uploader on every file row, so the
+   * admin UI can render `user.email` instead of the bare `creator` UUID.
+   * Joins `files.creator` → `users.id`. Only applied when the `users` table is
+   * actually registered in the app (see `findFiles`) — the files module stays
+   * usable standalone, without `alepha/api/users`. Targets the default `users`
+   * table, so creators in non-default realms come back unmatched (`user`
+   * undefined), which the UI handles by falling back to `creatorName`.
+   *
+   * The `users` entity is resolved from the repository registry at runtime
+   * rather than imported: the users module already depends on the files module
+   * (avatars), so a compile-time import here would form a circular dependency.
+   */
+  protected resolveCreatorJoin(): {
+    user: {
+      join: import("alepha/orm").EntityPrimitive<import("typebox").TObject<import("typebox").TProperties>>;
+      on: ["creator", {
+        name: string;
+      }];
+    };
+  } | undefined;
+  protected onUploadFile: import("alepha").HookPrimitive<"bucket:file:uploaded">;
+  protected onDeleteBucketFile: import("alepha").HookPrimitive<"bucket:file:deleted">;
   /**
    * Calculates SHA-256 checksum of a file.
    *
+   * Reads the whole file into memory. Callers that already hold the bytes
+   * should use {@link hashBuffer} instead to avoid re-reading — re-reading a
+   * one-shot stream either yields the wrong hash or drains a stream another
+   * step still needs.
+   *
    * @param file - The file to calculate checksum for
    * @returns Hexadecimal string representation of the SHA-256 hash
    * @protected
    */
   protected calculateChecksum(file: FileLike): Promise<string>;
+  /**
+   * Calculates the SHA-256 checksum of an already-read body.
+   *
+   * @param data - The file bytes
+   * @returns Hexadecimal string representation of the SHA-256 hash
+   * @protected
+   */
+  protected hashBuffer(data: ArrayBuffer): string;
   /**
    * Gets a bucket primitive by name.
    *
@@ -514,14 +552,35 @@ declare class FileService {
     tags?: string[];
   }): Promise<FileEntity>;
   /**
-   * Streams a file from storage by its database ID.
+   * Persists the metadata row for an already-uploaded blob, deleting the
+   * blob if the insert fails. Uploads are not atomic: the blob is written to
+   * storage first (the row needs the returned `blobId`), so a failed insert
+   * would otherwise leak the blob — an orphaned blob with no DB row. This
+   * compensates by removing the blob, favouring the recoverable failure
+   * (a missing blob) over the worse one (a row pointing at nothing).
    *
-   * @param id - The database ID (UUID) of the file to stream
+   * Best-effort: cleanup runs with `skipHook` so it neither re-emits
+   * `bucket:file:deleted` nor touches the (non-existent) DB row, and a failed
+   * cleanup is logged rather than thrown. The original write error is always
+   * rethrown so callers still see the real failure.
+   *
+   * @param bucket - The bucket the blob was uploaded to
+   * @param blobId - The id returned by `bucket.upload`
+   * @param insert - Thunk performing the metadata insert
+   * @returns The created file entity
+   */
+  protected persistBlobMetadata(bucket: BucketPrimitive, blobId: string, insert: () => Promise<FileEntity>): Promise<FileEntity>;
+  /**
+   * Streams a file from storage by its database ID, or directly from an
+   * already-loaded `FileEntity` to avoid a duplicate DB roundtrip when the
+   * caller has already fetched the row (e.g. after an access check).
+   *
+   * @param id - The database ID (UUID) of the file, or the entity itself
    * @returns The file object ready for streaming/downloading
    * @throws {NotFoundError} If the file doesn't exist in the database
    * @throws {FileNotFoundError} If the file exists in database but not in storage
    */
-  streamFile(id: string): Promise<FileLike>;
+  streamFile(id: string | FileEntity): Promise<FileLike>;
   /**
    * Updates file metadata (name, tags, expiration date).
    * Does not modify the actual file content in storage.
@@ -567,6 +626,12 @@ declare class FileService {
   /**
    * Gets storage statistics including total size, file count, and breakdowns by bucket and MIME type.
    *
+   * Aggregated in SQL (`SUM`/`COUNT` + `GROUP BY`) rather than by loading
+   * every row into memory — the table can hold millions of files, and this
+   * endpoint must stay O(groups), not O(rows). Totals are derived from the
+   * per-bucket groups (every row has exactly one bucket), so no extra query
+   * is needed.
+   *
    * @returns Storage statistics with aggregated data
    */
   getStorageStats(): Promise<StorageStats>;
@@ -594,18 +659,18 @@ declare class AdminFileStatsController {
    * Returns aggregated data including total size, file count,
    * and breakdowns by bucket and MIME type.
    */
-  readonly getFileStats: _$alepha_server0.ActionPrimitiveFn<{
-    response: _$typebox.TObject<{
-      totalSize: _$typebox.TNumber;
-      totalFiles: _$typebox.TNumber;
-      byBucket: _$typebox.TArray<_$typebox.TObject<{
-        bucket: _$typebox.TString;
-        totalSize: _$typebox.TNumber;
-        fileCount: _$typebox.TNumber;
+  readonly getFileStats: import("alepha/server").ActionPrimitiveFn<{
+    response: import("typebox").TObject<{
+      totalSize: import("typebox").TNumber;
+      totalFiles: import("typebox").TNumber;
+      byBucket: import("typebox").TArray<import("typebox").TObject<{
+        bucket: import("typebox").TString;
+        totalSize: import("typebox").TNumber;
+        fileCount: import("typebox").TNumber;
       }>>;
-      byMimeType: _$typebox.TArray<_$typebox.TObject<{
-        mimeType: _$typebox.TString;
-        fileCount: _$typebox.TNumber;
+      byMimeType: import("typebox").TArray<import("typebox").TObject<{
+        mimeType: import("typebox").TString;
+        fileCount: import("typebox").TNumber;
       }>>;
     }>;
   }>;
@@ -642,6 +707,25 @@ declare class FileAccessProvider {
    * implementation is strict: only the uploader passes.
    */
   assertReadable(file: FileEntity, user: UserAccountToken | undefined): Promise<void>;
+  /**
+   * Throws when `file` may not be served through the anonymous
+   * `/public/files/:id` route. The default is deny-all: nothing is public
+   * unless this method is overridden. Throws `NotFoundError` (not 403) so the
+   * endpoint doesn't leak the existence of private file ids.
+   *
+   * Typical override matches on bucket name:
+   *
+   * ```ts
+   * class MyAccess extends FileAccessProvider {
+   *   async assertPublic(file) {
+   *     if (file.bucket === "avatars") return;
+   *     if (file.bucket === "campaign-icons") return;
+   *     return super.assertPublic(file);
+   *   }
+   * }
+   * ```
+   */
+  assertPublic(file: FileEntity): Promise<void>;
 }
 //#endregion
 //#region ../../src/api/files/controllers/FileController.d.ts
@@ -658,63 +742,70 @@ declare class FileController {
    * GET /files - Lists files with optional filtering and pagination.
    * Supports filtering by bucket and tags.
    */
-  readonly findFiles: _$alepha_server0.ActionPrimitiveFn<{
-    query: _$typebox.TObject<{
-      page: _$typebox.TOptional<_$typebox.TInteger>;
-      size: _$typebox.TOptional<_$typebox.TInteger>;
-      sort: _$typebox.TOptional<_$typebox.TString>;
-      bucket: _$typebox.TOptional<_$typebox.TString>;
-      tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-      name: _$typebox.TOptional<_$typebox.TString>;
-      mimeType: _$typebox.TOptional<_$typebox.TString>;
-      creator: _$typebox.TOptional<_$typebox.TString>;
-      createdAfter: _$typebox.TOptional<_$typebox.TString>;
-      createdBefore: _$typebox.TOptional<_$typebox.TString>;
+  readonly findFiles: import("alepha/server").ActionPrimitiveFn<{
+    query: import("typebox").TObject<{
+      page: import("typebox").TOptional<import("typebox").TInteger>;
+      size: import("typebox").TOptional<import("typebox").TInteger>;
+      sort: import("typebox").TOptional<import("typebox").TString>;
+      bucket: import("typebox").TOptional<import("typebox").TString>;
+      tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+      name: import("typebox").TOptional<import("typebox").TString>;
+      mimeType: import("typebox").TOptional<import("typebox").TString>;
+      creator: import("typebox").TOptional<import("typebox").TString>;
+      createdAfter: import("typebox").TOptional<import("typebox").TString>;
+      createdBefore: import("typebox").TOptional<import("typebox").TString>;
     }>;
-    response: _$alepha.TPage<_$typebox.TObject<{
-      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
-      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
-      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
-      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
-      blobId: _$typebox.TString;
-      creator: _$typebox.TOptional<_$typebox.TString>;
-      creatorRealm: _$typebox.TOptional<_$typebox.TString>;
-      creatorName: _$typebox.TOptional<_$typebox.TString>;
-      bucket: _$typebox.TString;
-      expirationDate: _$typebox.TOptional<_$typebox.TString>;
-      name: _$typebox.TString;
-      originalName: _$typebox.TOptional<_$typebox.TString>;
-      size: _$typebox.TNumber;
-      mimeType: _$typebox.TString;
-      tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-      checksum: _$typebox.TOptional<_$typebox.TString>;
+    response: import("alepha").TPage<import("typebox").TObject<{
+      id: PgAttr<PgAttr<import("typebox").TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<import("typebox").TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<import("typebox").TString, typeof PG_ORGANIZATION>;
+      blobId: import("typebox").TString;
+      creator: import("typebox").TOptional<import("typebox").TString>;
+      creatorRealm: import("typebox").TOptional<import("typebox").TString>;
+      creatorName: import("typebox").TOptional<import("typebox").TString>;
+      bucket: import("typebox").TString;
+      expirationDate: import("typebox").TOptional<import("typebox").TString>;
+      name: import("typebox").TString;
+      originalName: import("typebox").TOptional<import("typebox").TString>;
+      size: import("typebox").TNumber;
+      mimeType: import("typebox").TString;
+      tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+      checksum: import("typebox").TOptional<import("typebox").TString>;
+      user: import("typebox").TOptional<import("typebox").TObject<{
+        id: import("typebox").TString;
+        email: import("typebox").TOptional<import("typebox").TString>;
+        username: import("typebox").TOptional<import("typebox").TString>;
+        firstName: import("typebox").TOptional<import("typebox").TString>;
+        lastName: import("typebox").TOptional<import("typebox").TString>;
+      }>>;
     }>>;
   }>;
   /**
    * DELETE /files/:id - Deletes a file from both storage and database.
    * Removes the file from the bucket and cleans up the database record.
    */
-  readonly deleteFile: _$alepha_server0.ActionPrimitiveFn<{
-    params: _$typebox.TObject<{
-      id: _$typebox.TString;
+  readonly deleteFile: import("alepha/server").ActionPrimitiveFn<{
+    params: import("typebox").TObject<{
+      id: import("typebox").TString;
     }>;
-    response: _$typebox.TObject<{
-      ok: _$typebox.TBoolean;
-      id: _$typebox.TOptional<_$typebox.TUnion<[_$typebox.TString, _$typebox.TInteger]>>;
-      count: _$typebox.TOptional<_$typebox.TNumber>;
+    response: import("typebox").TObject<{
+      ok: import("typebox").TBoolean;
+      id: import("typebox").TOptional<import("typebox").TUnion<[import("typebox").TString, import("typebox").TInteger]>>;
+      count: import("typebox").TOptional<import("typebox").TNumber>;
     }>;
   }>;
   /**
    * POST /files/delete - Delete many files in one request, batching the
    * underlying bucket calls per bucket (R2/S3 batch where supported).
    */
-  readonly deleteFiles: _$alepha_server0.ActionPrimitiveFn<{
-    body: _$typebox.TObject<{
-      ids: _$typebox.TArray<_$typebox.TString>;
+  readonly deleteFiles: import("alepha/server").ActionPrimitiveFn<{
+    body: import("typebox").TObject<{
+      ids: import("typebox").TArray<import("typebox").TString>;
     }>;
-    response: _$typebox.TObject<{
-      deleted: _$typebox.TArray<_$typebox.TString>;
+    response: import("typebox").TObject<{
+      deleted: import("typebox").TArray<import("typebox").TString>;
     }>;
   }>;
   /**
@@ -722,65 +813,79 @@ declare class FileController {
    * Creates a database record with metadata and calculates checksum.
    * Optionally specify bucket and expiration date.
    */
-  readonly uploadFile: _$alepha_server0.ActionPrimitiveFn<{
-    body: _$typebox.TObject<{
-      file: _$alepha.TFile;
+  readonly uploadFile: import("alepha/server").ActionPrimitiveFn<{
+    body: import("typebox").TObject<{
+      file: import("alepha").TFile;
     }>;
-    query: _$typebox.TObject<{
-      expirationDate: _$typebox.TOptional<_$typebox.TString>;
-      bucket: _$typebox.TOptional<_$typebox.TString>;
+    query: import("typebox").TObject<{
+      expirationDate: import("typebox").TOptional<import("typebox").TString>;
+      bucket: import("typebox").TOptional<import("typebox").TString>;
     }>;
-    response: _$typebox.TObject<{
-      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
-      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
-      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
-      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
-      blobId: _$typebox.TString;
-      creator: _$typebox.TOptional<_$typebox.TString>;
-      creatorRealm: _$typebox.TOptional<_$typebox.TString>;
-      creatorName: _$typebox.TOptional<_$typebox.TString>;
-      bucket: _$typebox.TString;
-      expirationDate: _$typebox.TOptional<_$typebox.TString>;
-      name: _$typebox.TString;
-      originalName: _$typebox.TOptional<_$typebox.TString>;
-      size: _$typebox.TNumber;
-      mimeType: _$typebox.TString;
-      tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-      checksum: _$typebox.TOptional<_$typebox.TString>;
+    response: import("typebox").TObject<{
+      id: PgAttr<PgAttr<import("typebox").TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<import("typebox").TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<import("typebox").TString, typeof PG_ORGANIZATION>;
+      blobId: import("typebox").TString;
+      creator: import("typebox").TOptional<import("typebox").TString>;
+      creatorRealm: import("typebox").TOptional<import("typebox").TString>;
+      creatorName: import("typebox").TOptional<import("typebox").TString>;
+      bucket: import("typebox").TString;
+      expirationDate: import("typebox").TOptional<import("typebox").TString>;
+      name: import("typebox").TString;
+      originalName: import("typebox").TOptional<import("typebox").TString>;
+      size: import("typebox").TNumber;
+      mimeType: import("typebox").TString;
+      tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+      checksum: import("typebox").TOptional<import("typebox").TString>;
+      user: import("typebox").TOptional<import("typebox").TObject<{
+        id: import("typebox").TString;
+        email: import("typebox").TOptional<import("typebox").TString>;
+        username: import("typebox").TOptional<import("typebox").TString>;
+        firstName: import("typebox").TOptional<import("typebox").TString>;
+        lastName: import("typebox").TOptional<import("typebox").TString>;
+      }>>;
     }>;
   }>;
   /**
    * PATCH /files/:id - Updates file metadata.
    * Allows updating name, tags, and expiration date without modifying file content.
    */
-  readonly updateFile: _$alepha_server0.ActionPrimitiveFn<{
-    params: _$typebox.TObject<{
-      id: _$typebox.TString;
+  readonly updateFile: import("alepha/server").ActionPrimitiveFn<{
+    params: import("typebox").TObject<{
+      id: import("typebox").TString;
     }>;
-    body: _$typebox.TObject<{
-      name: _$typebox.TOptional<_$typebox.TString>;
-      tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-      expirationDate: _$typebox.TOptional<_$typebox.TString>;
+    body: import("typebox").TObject<{
+      name: import("typebox").TOptional<import("typebox").TString>;
+      tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+      expirationDate: import("typebox").TOptional<import("typebox").TString>;
     }>;
-    response: _$typebox.TObject<{
-      id: PgAttr<PgAttr<_$typebox.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
-      version: PgAttr<PgAttr<_$typebox.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
-      createdAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-      updatedAt: PgAttr<PgAttr<_$typebox.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
-      organizationId: PgAttr<_$typebox.TString, typeof PG_ORGANIZATION>;
-      blobId: _$typebox.TString;
-      creator: _$typebox.TOptional<_$typebox.TString>;
-      creatorRealm: _$typebox.TOptional<_$typebox.TString>;
-      creatorName: _$typebox.TOptional<_$typebox.TString>;
-      bucket: _$typebox.TString;
-      expirationDate: _$typebox.TOptional<_$typebox.TString>;
-      name: _$typebox.TString;
-      originalName: _$typebox.TOptional<_$typebox.TString>;
-      size: _$typebox.TNumber;
-      mimeType: _$typebox.TString;
-      tags: _$typebox.TOptional<_$typebox.TArray<_$typebox.TString>>;
-      checksum: _$typebox.TOptional<_$typebox.TString>;
+    response: import("typebox").TObject<{
+      id: PgAttr<PgAttr<import("typebox").TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+      version: PgAttr<PgAttr<import("typebox").TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+      createdAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+      updatedAt: PgAttr<PgAttr<import("typebox").TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+      organizationId: PgAttr<import("typebox").TString, typeof PG_ORGANIZATION>;
+      blobId: import("typebox").TString;
+      creator: import("typebox").TOptional<import("typebox").TString>;
+      creatorRealm: import("typebox").TOptional<import("typebox").TString>;
+      creatorName: import("typebox").TOptional<import("typebox").TString>;
+      bucket: import("typebox").TString;
+      expirationDate: import("typebox").TOptional<import("typebox").TString>;
+      name: import("typebox").TString;
+      originalName: import("typebox").TOptional<import("typebox").TString>;
+      size: import("typebox").TNumber;
+      mimeType: import("typebox").TString;
+      tags: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+      checksum: import("typebox").TOptional<import("typebox").TString>;
+      user: import("typebox").TOptional<import("typebox").TObject<{
+        id: import("typebox").TString;
+        email: import("typebox").TOptional<import("typebox").TString>;
+        username: import("typebox").TOptional<import("typebox").TString>;
+        firstName: import("typebox").TOptional<import("typebox").TString>;
+        lastName: import("typebox").TOptional<import("typebox").TString>;
+      }>>;
     }>;
   }>;
   /**
@@ -794,20 +899,61 @@ declare class FileController {
    * Cache-Control is `private` because the per-user authorization decision
    * cannot be cached by shared proxies/CDNs. Client-side ETag still works.
    */
-  readonly streamFile: _$alepha_server0.ActionPrimitiveFn<{
-    params: _$typebox.TObject<{
-      id: _$typebox.TString;
+  readonly streamFile: import("alepha/server").ActionPrimitiveFn<{
+    params: import("typebox").TObject<{
+      id: import("typebox").TString;
     }>;
-    response: _$alepha.TFile;
+    response: import("alepha").TFile;
+  }>;
+  /**
+   * GET /public/files/:id - Anonymous, edge-cacheable download.
+   *
+   * Authorization is delegated to `FileAccessProvider.assertPublic`. The
+   * default policy is deny-all (throws `NotFoundError`), so consuming apps
+   * must override the provider to opt files in — typically by bucket name
+   * (avatars, campaign icons, etc.).
+   *
+   * Cache-Control is `public, immutable, max-age=1y` so Cloudflare's edge
+   * cache and any intermediary proxy can serve subsequent hits without
+   * touching the Worker. The split URL prefix (vs `/files/:id`) is what
+   * makes this safe: edge cache is URL-keyed, so public and private files
+   * live in separate cache lanes.
+   */
+  readonly streamPublicFile: import("alepha/server").ActionPrimitiveFn<{
+    params: import("typebox").TObject<{
+      id: import("typebox").TString;
+    }>;
+    response: import("alepha").TFile;
   }>;
 }
 //#endregion
 //#region ../../src/api/files/jobs/FileJobs.d.ts
 declare class FileJobs {
   protected readonly fileService: FileService;
-  readonly purgeFiles: _$alepha_scheduler0.SchedulerPrimitive;
+  readonly purgeFiles: import("alepha/scheduler").SchedulerPrimitive;
 }
 //#endregion
+//#region ../../src/api/files/schemas/fileCreatorSummarySchema.d.ts
+/**
+ * Slim view of a file's uploader, embedded by the admin listing via a
+ * best-effort left join (`files.creator` → `users.id`) so the UI can render
+ * a human-readable identifier instead of a bare UUID.
+ *
+ * Optional end-to-end: the join only runs when the `users` entity is
+ * registered in the running app (see `FileService.findFiles`), and even then
+ * a file whose creator was deleted — or who lives in a non-default realm —
+ * comes back with `user` undefined. Callers must fall back to `creatorName`
+ * or the raw `creator` id.
+ */
+declare const fileCreatorSummarySchema: import("typebox").TObject<{
+  id: import("typebox").TString;
+  email: import("typebox").TOptional<import("typebox").TString>;
+  username: import("typebox").TOptional<import("typebox").TString>;
+  firstName: import("typebox").TOptional<import("typebox").TString>;
+  lastName: import("typebox").TOptional<import("typebox").TString>;
+}>;
+type FileCreatorSummary = Static<typeof fileCreatorSummarySchema>;
+//#endregion
 //#region ../../src/api/files/index.d.ts
 declare module "alepha/bucket" {
   interface BucketFileOptions {
@@ -842,7 +988,7 @@ declare module "alepha/bucket" {
  *
  * @module alepha.api.files
  */
-declare const AlephaApiFiles: _$alepha.Service<_$alepha.Module>;
+declare const AlephaApiFiles: import("alepha").Service<import("alepha").Module>;
 //#endregion
-export { AdminFileStatsController, AlephaApiFiles, BucketStats, FileAccessProvider, FileController, FileEntity, FileJobs, FileService, MimeTypeStats, StorageStats, bucketStatsSchema, files, mimeTypeStatsSchema, storageStatsSchema };
+export { AdminFileStatsController, AlephaApiFiles, BucketStats, FileAccessProvider, FileController, FileCreatorSummary, FileEntity, FileJobs, FileQuery, FileResource, FileService, MimeTypeStats, StorageStats, bucketStatsSchema, fileCreatorSummarySchema, fileQuerySchema, fileResourceSchema, files, mimeTypeStatsSchema, storageStatsSchema };
 //# sourceMappingURL=index.d.ts.map