Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -2,7 +2,7 @@
//
// Pure-ish server logic: builds/queries File rows (always tenant-scoped),
// orchestrates chunked upload + assembly, enforces visibility (404, not 403),
// and fans out to the scan/preview queues. NO React/UI imports. Routes call
// and starts the scan -> clean -> preview queue chain. NO React/UI imports. Routes call
// these functions from their loaders/actions and build the View-Model from the
// returned rows.
//
@@ -19,12 +19,11 @@
// goes through *WithTx(tx, ...) helpers that take the active transaction client.
import { CatalogError, foundationErrors } from "@hivegrid/foundation";
import { publishOutboxEvent, type OutboxPublisherTransaction } from "@hivegrid/db/outbox";
import { buildPortalDocumentReadyOutboxEvent } from "@hivegrid/queue";
import { filesIndex } from "@hivegrid/search";
import { buildFileStorageKeys, buildUploadChunkKey, uploadChunkPrefix } from "@hivegrid/storage";
import {
FILE_UPLOAD_CHUNK_SIZE_BYTES,
FILE_UPLOAD_MAX_FILE_SIZE_BYTES,
} from "@hivegrid/view-models";
import { FILE_UPLOAD_CHUNK_SIZE_BYTES, FILE_UPLOAD_MAX_FILE_SIZE_BYTES } from "@hivegrid/view-models";
import { publishFileSearchUpsert, publishSearchProjectionDelete } from "~/services/search/searchIndexProjection.server";
import { withTenantRLS, type TenantRlsClient } from "~/utils/db/.server/tenantRls.server";
import { getTenantUsers } from "~/utils/db/tenants.db.server";
@@ -34,7 +33,18 @@ import type { Prisma } from "@hivegrid/db/prisma-browser";
import { assembleChunkedUpload, deleteFile, putBufferAsFile, resolveStorageBucket, storeFile } from "./storageService";
import { enqueueFileScan } from "./fileScanQueue.server";
import { enqueueFilePreview } from "./filePreviewQueue.server";
import type { ScanContext } from "@hivegrid/storage";
import { assertTenantStorageReservation, TenantStorageCapacityError } from "~/services/billing/storage-capacity.server";
import { createMagicBytesScanAdapter, DEFAULT_ALLOW_LIST, type PreUploadScanAdapter, type ScanContext } from "@hivegrid/storage";
import {
assertFileLinkTargetVisibleWithTx,
createFileVisibilityQueryState,
fileReadScopeWhereWithTx,
filterVisibleFileLinksWithTx,
type FileVisibilityContext,
type FileVisibilityQueryState,
} from "./fileVisibility.server";
export type { FileVisibilityContext } from "./fileVisibility.server";
/**
* Domain error carrying an i18n message key (M002 Klartext). Routes map
@@ -60,7 +70,9 @@ export type FileEntityType =
| "order"
| "task"
| "appointment"
| "signature_document";
| "signature_document"
| "email_message"
| "chat_message";
export type FileSource = "manual_upload" | "customer_portal" | "form_submission" | "email_attachment" | "automation" | "api";
@@ -78,6 +90,11 @@ export const FILES_ALLOWED_MIME_TYPES: ReadonlySet<string> = new Set([
"image/gif",
"image/heic",
"image/heif",
"audio/webm",
"audio/ogg",
"audio/mpeg",
"audio/mp4",
"audio/wav",
"application/pdf",
"text/plain",
"text/markdown",
@@ -87,15 +104,13 @@ export const FILES_ALLOWED_MIME_TYPES: ReadonlySet<string> = new Set([
"application/vnd.openxmlformats-officedocument.presentationml.presentation",
]);
export type FileVisibilityContext = {
userId: string;
/** The user's permission names for this tenant (from getPermissionsByUser). */
permissions: readonly string[];
};
function hasPermission(ctx: FileVisibilityContext, permission: string): boolean {
return ctx.permissions.includes(permission);
}
const filesMagicBytesScanner: PreUploadScanAdapter = createMagicBytesScanAdapter({
allowList: {
...DEFAULT_ALLOW_LIST,
formUpload: [...FILES_ALLOWED_MIME_TYPES],
},
enabled: process.env.STORAGE_SCAN_LAYER1_ENABLED !== "false",
});
// --- Upload session -------------------------------------------------------
@@ -120,29 +135,48 @@ export async function createUploadSession(input: CreateUploadSessionInput): Prom
if (input.totalSizeBytes > FILE_UPLOAD_MAX_FILE_SIZE_BYTES) {
throw new FileServiceError("files.error.tooLarge");
}
if (!FILES_ALLOWED_MIME_TYPES.has(input.mimeType)) {
const mimeType = normalizeUploadMimeType(input.mimeType);
if (!FILES_ALLOWED_MIME_TYPES.has(mimeType)) {
throw new FileServiceError("files.error.mimeBlocked");
}
const totalChunks = Math.max(1, Math.ceil(input.totalSizeBytes / FILE_UPLOAD_CHUNK_SIZE_BYTES));
const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000);
const upload = await withTenantRLS(input.tenantId, (tx) =>
tx.fileUpload.create({
const upload = await withTenantRLS(input.tenantId, async (tx) => {
try {
await assertTenantStorageReservation(tx, input.tenantId, input.totalSizeBytes);
} catch (error) {
if (error instanceof TenantStorageCapacityError) {
throw new FileServiceError(
error.code === "STORAGE_PLAN_REQUIRED" ? "files.error.storagePlanRequired" : "files.error.storageQuotaExceeded",
);
}
throw error;
}
return tx.fileUpload.create({
data: {
tenantId: input.tenantId,
createdByUserId: input.userId,
originalFilename: input.originalFilename,
totalSizeBytes: input.totalSizeBytes,
mimeType: input.mimeType,
mimeType,
totalChunks,
status: "in_progress",
expiresAt,
},
select: { id: true },
}),
);
});
});
return { uploadId: upload.id, chunkSize: FILE_UPLOAD_CHUNK_SIZE_BYTES, totalChunks };
}
/** Browsers commonly append codec parameters to MediaRecorder MIME values. */
export function normalizeUploadMimeType(value: string): string {
const mimeType = value.split(";", 1)[0]?.trim().toLowerCase() ?? "";
if (mimeType === "audio/x-m4a") return "audio/mp4";
if (mimeType === "audio/x-wav") return "audio/wav";
return mimeType;
}
export type StoreUploadChunkInput = {
tenantId: string;
userId: string;
@@ -151,12 +185,75 @@ export type StoreUploadChunkInput = {
bytes: Uint8Array;
};
export function expectedUploadChunkSize({
totalSizeBytes,
totalChunks,
chunkIndex,
}: {
totalSizeBytes: number;
totalChunks: number;
chunkIndex: number;
}): number {
if (
!Number.isSafeInteger(totalSizeBytes) ||
totalSizeBytes <= 0 ||
!Number.isSafeInteger(totalChunks) ||
totalChunks <= 0 ||
!Number.isSafeInteger(chunkIndex) ||
chunkIndex < 0 ||
chunkIndex >= totalChunks
) {
throw new FileServiceError("files.error.uploadIncomplete");
}
const expectedTotalChunks = Math.ceil(totalSizeBytes / FILE_UPLOAD_CHUNK_SIZE_BYTES);
if (totalChunks !== expectedTotalChunks) {
throw new FileServiceError("files.error.uploadIncomplete");
}
if (chunkIndex < totalChunks - 1) {
return FILE_UPLOAD_CHUNK_SIZE_BYTES;
}
return totalSizeBytes - FILE_UPLOAD_CHUNK_SIZE_BYTES * (totalChunks - 1);
}
export function assertUploadChunkManifest({
totalSizeBytes,
totalChunks,
chunks,
}: {
totalSizeBytes: number;
totalChunks: number;
chunks: readonly { chunkIndex: number; sizeBytes: number }[];
}): void {
if (chunks.length !== totalChunks) {
throw new FileServiceError("files.error.uploadIncomplete");
}
let receivedSizeBytes = 0;
for (let index = 0; index < chunks.length; index += 1) {
const chunk = chunks[index];
if (chunk.chunkIndex !== index || chunk.sizeBytes !== expectedUploadChunkSize({ totalSizeBytes, totalChunks, chunkIndex: index })) {
throw new FileServiceError("files.error.uploadIncomplete");
}
receivedSizeBytes += chunk.sizeBytes;
}
if (receivedSizeBytes !== totalSizeBytes) {
throw new FileServiceError("files.error.uploadIncomplete");
}
}
export async function storeUploadChunk(input: StoreUploadChunkInput): Promise<{ receivedChunks: number; totalChunks: number }> {
const upload = await withTenantRLS(input.tenantId, (tx) =>
tx.fileUpload.findFirst({
where: { id: input.uploadId, tenantId: input.tenantId, createdByUserId: input.userId },
select: { id: true, status: true, totalChunks: true, expiresAt: true },
}),
select: {
id: true,
status: true,
totalChunks: true,
totalSizeBytes: true,
originalFilename: true,
mimeType: true,
expiresAt: true,
},
})
);
if (!upload) {
throw new CatalogError(foundationErrors.notFound, { uploadId: input.uploadId });
@@ -170,6 +267,25 @@ export async function storeUploadChunk(input: StoreUploadChunkInput): Promise<{
if (input.chunkIndex < 0 || input.chunkIndex >= upload.totalChunks) {
throw new FileServiceError("files.error.chunkIndexOutOfRange");
}
const expectedSizeBytes = expectedUploadChunkSize({
totalSizeBytes: upload.totalSizeBytes,
totalChunks: upload.totalChunks,
chunkIndex: input.chunkIndex,
});
if (input.bytes.byteLength !== expectedSizeBytes) {
throw new FileServiceError("files.error.uploadIncomplete");
}
if (input.chunkIndex === 0) {
const scanResult = await filesMagicBytesScanner.scan({
buffer: input.bytes,
declaredMimeType: upload.mimeType,
filename: upload.originalFilename,
context: "formUpload",
});
if (scanResult.status === "rejected") {
throw new FileServiceError("files.error.mimeBlocked");
}
}
const bucket = resolveStorageBucket();
const chunkKey = buildUploadChunkKey(input.tenantId, input.uploadId, input.chunkIndex);
@@ -244,17 +360,13 @@ export async function completeUpload(input: CompleteUploadInput): Promise<Comple
const manifest = await tx.fileUploadChunk.findMany({
where: { uploadId: input.uploadId, tenantId: input.tenantId },
orderBy: { chunkIndex: "asc" },
select: { chunkIndex: true, storageKey: true },
select: { chunkIndex: true, storageKey: true, sizeBytes: true },
});
assertUploadChunkManifest({
totalSizeBytes: session.totalSizeBytes,
totalChunks: session.totalChunks,
chunks: manifest,
});
if (manifest.length !== session.totalChunks) {
throw new FileServiceError("files.error.uploadIncomplete");
}
// Verify contiguous 0..totalChunks-1 ordering.
for (let index = 0; index < manifest.length; index += 1) {
if (manifest[index].chunkIndex !== index) {
throw new FileServiceError("files.error.uploadIncomplete");
}
}
const created = await tx.file.create({
data: {
@@ -307,18 +419,10 @@ export async function completeUpload(input: CompleteUploadInput): Promise<Comple
await tx.fileUpload.update({ where: { id: input.uploadId }, data: { status: "completed", targetFileId: file.id } });
});
// Fan out async scan (ClamAV, layer 2) + preview generation. When scanning is
// disabled (dev / SCAN_QUEUE_ENABLED!=true) the enqueue is a no-op; in that
// case mark the file scanStatus=skipped so the fail-closed media proxy (§6)
// still serves it. In prod the file stays scanStatus=pending until the worker
// writes a clean/infected verdict.
const scanResult = await enqueueFileScan({ bucket, key: original, tenantId: input.tenantId, contentType: upload.mimeType, fileId: file.id }).catch(
() => ({ enqueued: false, reason: "queue-unavailable" }) as const,
);
if (!scanResult.enqueued && scanResult.reason === "scan-disabled") {
await withTenantRLS(input.tenantId, (tx) => tx.file.update({ where: { id: file.id }, data: { scanStatus: "skipped" } })).catch(() => {});
}
await enqueueFilePreview({ fileId: file.id, tenantId: input.tenantId, bucket, storageKey: original, mimeType: upload.mimeType }).catch(() => {});
// Enqueue only ClamAV here. The scan worker persists a clean verdict before
// it enqueues the first preview, so untrusted bytes can never race an image
// or PDF decoder. Queue failures leave the file pending/non-deliverable.
await enqueueFileScan({ bucket, key: original, tenantId: input.tenantId, contentType: upload.mimeType, fileId: file.id }).catch(() => undefined);
return { id: file.id, displayName: file.displayName, mimeType: file.mimeType, sizeBytes: file.sizeBytes, storageKey: original };
}
@@ -338,7 +442,8 @@ export type CreateFileFromBytesInput = {
* Single-request upload: create a File from an in-memory byte buffer (no chunked
* session). Mirrors the finalize tail of {@link completeUpload} — pending row →
* fail-closed magic-bytes scan + storage PUT → finalize storageKey + search
* upsert → fan out ClamAV (layer 2) + preview. Callers gate on their OWN
* upsert → enqueue ClamAV (layer 2), which schedules preview only after a
* clean verdict. Callers gate on their OWN
* permission (e.g. HR self-upload gates on hr.read_own, NOT files.write). A
* rejected scan throws {@link StorageScanRejectedError} and leaves no orphan row.
*/
@@ -348,8 +453,18 @@ export async function createFileFromBytes(input: CreateFileFromBytesInput): Prom
const sizeBytes = input.bytes.byteLength;
// 1. Pending File row (id needed for the storage key).
const file = await withTenantRLS(input.tenantId, (tx) =>
tx.file.create({
const file = await withTenantRLS(input.tenantId, async (tx) => {
try {
await assertTenantStorageReservation(tx, input.tenantId, sizeBytes);
} catch (error) {
if (error instanceof TenantStorageCapacityError) {
throw new FileServiceError(
error.code === "STORAGE_PLAN_REQUIRED" ? "files.error.storagePlanRequired" : "files.error.storageQuotaExceeded",
);
}
throw error;
}
return tx.file.create({
data: {
tenantId: input.tenantId,
createdByUserId: input.userId,
@@ -363,8 +478,8 @@ export async function createFileFromBytes(input: CreateFileFromBytesInput): Prom
scanStatus: "pending",
},
select: { id: true, displayName: true, mimeType: true, sizeBytes: true },
}),
);
});
});
const bucket = resolveStorageBucket();
const { original } = buildFileStorageKeys(input.tenantId, file.id);
@@ -393,15 +508,8 @@ export async function createFileFromBytes(input: CreateFileFromBytesInput): Prom
await publishFileSearchUpsert(tx, updated);
});
// 4. Fan out ClamAV (layer 2) + preview. When scanning is disabled, mark the
// file scanStatus=skipped so the fail-closed media proxy still serves it.
const scanResult = await enqueueFileScan({ bucket, key: original, tenantId: input.tenantId, contentType: mimeType, fileId: file.id }).catch(
() => ({ enqueued: false, reason: "queue-unavailable" }) as const,
);
if (!scanResult.enqueued && scanResult.reason === "scan-disabled") {
await withTenantRLS(input.tenantId, (tx) => tx.file.update({ where: { id: file.id }, data: { scanStatus: "skipped" } })).catch(() => {});
}
await enqueueFilePreview({ fileId: file.id, tenantId: input.tenantId, bucket, storageKey: original, mimeType }).catch(() => {});
// 4. Enqueue ClamAV only. The clean-verdict worker schedules the preview.
await enqueueFileScan({ bucket, key: original, tenantId: input.tenantId, contentType: mimeType, fileId: file.id }).catch(() => undefined);
return { id: file.id, displayName: file.displayName, mimeType: file.mimeType, sizeBytes: file.sizeBytes };
}
@@ -428,49 +536,62 @@ export type FileRow = {
archivedAt: Date | null;
};
/**
* Owner/link visibility for files.read_own (§7). Visible when the user owns or
* is assigned the file, OR holds files.read_all, OR a readable FileEntityLink
* exists. v1 link-readability is minimal (the link's mere existence in-tenant);
* full transitive entity-permission checks are v2.
*/
export type OwnedFileScanStatus = "pending" | "clean" | "infected" | "skipped";
/** Narrow post-upload status lookup for callers that created the File. It is
* tenant-scoped, owner-scoped and RLS-bound so polling cannot become a generic
* File enumeration side channel. */
export async function getOwnedFileScanStatus(input: { tenantId: string; userId: string; fileId: string }): Promise<OwnedFileScanStatus> {
const file = await withTenantRLS(input.tenantId, (tx) =>
tx.file.findFirst({
where: {
id: input.fileId,
tenantId: input.tenantId,
createdByUserId: input.userId,
archivedAt: null,
},
select: { scanStatus: true },
})
);
if (!file) throw new CatalogError(foundationErrors.notFound, { fileId: input.fileId });
return file.scanStatus as OwnedFileScanStatus;
}
// Internal: visibility check on an already-loaded file, using the active RLS
// transaction client (no own transaction → safe to call inside withTenantRLS).
async function isFileVisibleWithTx(
tx: TenantRlsClient,
file: Pick<FileRow, "id" | "tenantId" | "createdByUserId" | "assignedToUserId">,
ctx: FileVisibilityContext,
ctx: FileVisibilityContext
): Promise<boolean> {
if (hasPermission(ctx, "files.read_all")) {
return true;
}
if (file.createdByUserId === ctx.userId || file.assignedToUserId === ctx.userId) {
return true;
}
const link = await tx.fileEntityLink.findFirst({
where: { fileId: file.id, tenantId: file.tenantId },
const visibility = await fileReadScopeWhereWithTx(tx, file.tenantId, ctx, [file.id]);
const visible = await tx.file.findFirst({
where: { id: file.id, tenantId: file.tenantId, ...visibility },
select: { id: true },
});
return Boolean(link);
return Boolean(visible);
}
export async function isFileVisible(file: Pick<FileRow, "id" | "tenantId" | "createdByUserId" | "assignedToUserId">, ctx: FileVisibilityContext): Promise<boolean> {
// Fast paths need no DB; only the link lookup opens a tenant-scoped transaction.
if (hasPermission(ctx, "files.read_all") || file.createdByUserId === ctx.userId || file.assignedToUserId === ctx.userId) {
return true;
}
export async function isFileVisible(
file: Pick<FileRow, "id" | "tenantId" | "createdByUserId" | "assignedToUserId">,
ctx: FileVisibilityContext
): Promise<boolean> {
return withTenantRLS(file.tenantId, (tx) => isFileVisibleWithTx(tx, file, ctx));
}
// Internal: load + visibility on the active transaction client (no own tx).
async function getVisibleFileOrThrowWithTx(tx: TenantRlsClient, tenantId: string, fileId: string, ctx: FileVisibilityContext): Promise<FileRow> {
const file = await tx.file.findFirst({ where: { id: fileId, tenantId } });
async function getVisibleFileOrThrowWithTx(
tx: TenantRlsClient,
tenantId: string,
fileId: string,
ctx: FileVisibilityContext,
queryState?: FileVisibilityQueryState
): Promise<FileRow> {
const visibility = await fileReadScopeWhereWithTx(tx, tenantId, ctx, [fileId], queryState);
const file = await tx.file.findFirst({ where: { id: fileId, tenantId, ...visibility } });
if (!file) {
throw new CatalogError(foundationErrors.notFound, { fileId });
}
if (!(await isFileVisibleWithTx(tx, file as FileRow, ctx))) {
throw new CatalogError(foundationErrors.notFound, { fileId });
}
return file as FileRow;
}
@@ -482,19 +603,17 @@ export async function getVisibleFileOrThrow(tenantId: string, fileId: string, ct
export type FileLink = { entityType: string; entityId: string; linkRole: string | null };
/** Load a file with its entity links (tenant-scoped + visibility), else 404. */
export async function getVisibleFileWithLinks(
tenantId: string,
fileId: string,
ctx: FileVisibilityContext,
): Promise<{ file: FileRow; links: FileLink[] }> {
export async function getVisibleFileWithLinks(tenantId: string, fileId: string, ctx: FileVisibilityContext): Promise<{ file: FileRow; links: FileLink[] }> {
return withTenantRLS(tenantId, async (tx) => {
const file = await getVisibleFileOrThrowWithTx(tx, tenantId, fileId, ctx);
const queryState = createFileVisibilityQueryState();
const file = await getVisibleFileOrThrowWithTx(tx, tenantId, fileId, ctx, queryState);
const links = await tx.fileEntityLink.findMany({
where: { fileId, tenantId },
select: { entityType: true, entityId: true, linkRole: true },
orderBy: { createdAt: "asc" },
});
return { file, links: links as FileLink[] };
const visibleLinks = await filterVisibleFileLinksWithTx(tx, tenantId, links, ctx, queryState);
return { file, links: visibleLinks };
});
}
@@ -504,52 +623,129 @@ export type ListFilesFilter = {
tags?: readonly string[];
assignedToUserId?: string | null;
includeArchived?: boolean;
/** Free-text search over the display name (case-insensitive substring). */
q?: string | null;
};
const MIME_GROUP_PREFIX: Record<string, string> = { image: "image/", pdf: "application/pdf", text: "text/" };
const FILE_TAG_SCAN_LIMIT = 500;
/** Rows per browser page — one screenful of grid tiles, not an endless table. */
export const FILE_BROWSER_PAGE_SIZE = 24;
/**
* List files for the browser (tenant-scoped + read_own visibility), newest
* first, cursor-paginated. Visibility for non-read_all users: owner/assignee or
* any linked file (v1 minimal, §7).
*/
export async function listFilesForBrowser(input: {
function canListFileAssignees(ctx: FileVisibilityContext): boolean {
return ["files.read_all", "files.admin", "app.settings.members.view"].some((permission) => ctx.permissions.includes(permission));
}
export type ListFilesForBrowserInput = {
tenantId: string;
ctx: FileVisibilityContext;
filter?: ListFilesFilter;
cursor?: string | null;
/** 1-based page of the browser listing. Out-of-range values clamp to page 1. */
page?: number | null;
limit?: number;
}): Promise<{ rows: FileRow[]; nextCursor: string | null }> {
const limit = Math.min(Math.max(input.limit ?? 50, 1), 100);
};
/** Rows of one page plus what a page footer needs to say where the user is. */
export type FileBrowserPage = { rows: FileRow[]; total: number; page: number; pageCount: number; pageSize: number };
function buildFileBrowserWhere(input: ListFilesForBrowserInput, visibility: Prisma.FileWhereInput): Prisma.FileWhereInput {
const filter = input.filter ?? {};
const mimePrefix = filter.mimeGroup ? MIME_GROUP_PREFIX[filter.mimeGroup] : undefined;
// Build the where clause on a typed mutable object (not spread-of-union) so the
// optional filters + visibility OR type-check cleanly against FileWhereInput.
// Keep optional filters on a typed mutable object so they compose cleanly
// with the central visibility scope.
const where: Prisma.FileWhereInput = { tenantId: input.tenantId };
if (!filter.includeArchived) where.archivedAt = null;
if (filter.assignedToUserId) where.assignedToUserId = filter.assignedToUserId;
if (filter.tags && filter.tags.length > 0) where.tags = { hasEvery: [...filter.tags] };
if (mimePrefix) where.mimeType = { startsWith: mimePrefix };
// The search box matches what the browser actually shows — the display name.
// A blank query is no filter at all, not a match on the empty string.
const q = filter.q?.trim();
if (q) where.displayName = { contains: q, mode: "insensitive" };
if (filter.entityType) {
where.links = { some: { tenantId: input.tenantId, entityType: filter.entityType as Prisma.FileEntityLinkWhereInput["entityType"] } };
}
if (!hasPermission(input.ctx, "files.read_all")) {
where.OR = [
{ createdByUserId: input.ctx.userId },
{ assignedToUserId: input.ctx.userId },
{ links: { some: { tenantId: input.tenantId } } },
];
}
const rows = await withTenantRLS(input.tenantId, (tx) =>
tx.file.findMany({
where,
orderBy: { createdAt: "desc" },
take: limit + 1,
...(input.cursor ? { cursor: { id: input.cursor }, skip: 1 } : {}),
}),
);
const nextCursor = rows.length > limit ? rows[limit - 1].id : null;
return { rows: rows.slice(0, limit) as FileRow[], nextCursor };
Object.assign(where, visibility);
return where;
}
async function listFilesForBrowserWithTx(
tx: TenantRlsClient,
input: ListFilesForBrowserInput,
visibility: Prisma.FileWhereInput
): Promise<FileBrowserPage> {
const pageSize = Math.min(Math.max(input.limit ?? FILE_BROWSER_PAGE_SIZE, 1), 100);
const where = buildFileBrowserWhere(input, visibility);
const total = await tx.file.count({ where });
const pageCount = Math.max(1, Math.ceil(total / pageSize));
// A page number past the end (stale link, filter narrowed after paging) must
// land on a page that exists instead of on an empty list that reads like
// "no files".
const requested = Math.trunc(input.page ?? 1);
const page = Math.min(Math.max(Number.isFinite(requested) ? requested : 1, 1), pageCount);
const rows = await tx.file.findMany({
where,
// `id` breaks ties: two files uploaded in the same millisecond would
// otherwise be free to swap places between two page queries and appear
// twice, or not at all.
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
skip: (page - 1) * pageSize,
take: pageSize,
});
return { rows: rows as FileRow[], total, page, pageCount, pageSize };
}
/**
* List one page of files for the browser (tenant-scoped + read_own visibility),
* newest first. Project links only extend visibility when their target project
* is readable under the same project and pipeline access rules.
*/
export async function listFilesForBrowser(input: ListFilesForBrowserInput): Promise<FileBrowserPage> {
return withTenantRLS(input.tenantId, async (tx) => {
const visibility = await fileReadScopeWhereWithTx(tx, input.tenantId, input.ctx);
return listFilesForBrowserWithTx(tx, input, visibility);
});
}
/** Ids of the files sitting next to one file in the browser's own ordering. */
export type FileNeighbours = { previousId: string | null; nextId: string | null };
/**
* The file before and after `fileId` in the browser's order (newest first, id as
* tie-break), so the detail view can page through the library without going back
* to the list. Same visibility scope as the browser: a neighbour the reader may
* not open is not a neighbour. Archived files stay among their own kind — from
* an archived file the reader pages through the archive, not into the live list.
*/
export async function findFileNeighbours(input: { tenantId: string; ctx: FileVisibilityContext; fileId: string }): Promise<FileNeighbours> {
return withTenantRLS(input.tenantId, async (tx) => {
const visibility = await fileReadScopeWhereWithTx(tx, input.tenantId, input.ctx);
const current = await tx.file.findFirst({
where: { id: input.fileId, tenantId: input.tenantId, ...visibility },
select: { id: true, createdAt: true, archivedAt: true },
});
if (!current) return { previousId: null, nextId: null };
const base: Prisma.FileWhereInput = {
tenantId: input.tenantId,
...(current.archivedAt ? { NOT: { archivedAt: null } } : { archivedAt: null }),
...visibility,
};
// Composite (createdAt, id) comparison — `createdAt` alone would skip or
// repeat files uploaded within the same millisecond.
const [previous, next] = await Promise.all([
tx.file.findFirst({
where: { ...base, OR: [{ createdAt: { gt: current.createdAt } }, { createdAt: current.createdAt, id: { gt: current.id } }] },
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
select: { id: true },
}),
tx.file.findFirst({
where: { ...base, OR: [{ createdAt: { lt: current.createdAt } }, { createdAt: current.createdAt, id: { lt: current.id } }] },
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
select: { id: true },
}),
]);
return { previousId: previous?.id ?? null, nextId: next?.id ?? null };
});
}
export type FileFilterOptions = {
@@ -561,46 +757,89 @@ export type FileFilterOptions = {
assignees: { id: string; name: string }[];
};
type FileFilterRows = {
tagRows: Array<{ tags: string[] }>;
entityTypeRows: Array<{ entityType: string }>;
};
async function loadFileFilterRowsWithTx(tx: TenantRlsClient, tenantId: string, visibility: Prisma.FileWhereInput): Promise<FileFilterRows> {
const [tagRows, entityTypeRows] = await Promise.all([
tx.file.findMany({
where: { tenantId, ...visibility },
select: { tags: true },
orderBy: { createdAt: "desc" },
take: FILE_TAG_SCAN_LIMIT,
}),
tx.fileEntityLink.findMany({
where: { tenantId, file: { is: { tenantId, ...visibility } } },
select: { entityType: true },
distinct: ["entityType"],
orderBy: { entityType: "asc" },
}),
]);
return { tagRows, entityTypeRows };
}
function buildFileFilterOptions(rows: FileFilterRows, members: Awaited<ReturnType<typeof getTenantUsers>>): FileFilterOptions {
const tags = Array.from(new Set(rows.tagRows.flatMap((row) => row.tags))).sort((a, b) => a.localeCompare(b));
const entityTypes = rows.entityTypeRows.map((row) => row.entityType);
const assignees = members.map((member) => ({ id: member.user.id, name: fullName(member.user) })).sort((a, b) => a.name.localeCompare(b.name));
return { entityTypes, tags, assignees };
}
/**
* Build the option lists for the browser filter dropdowns (tenant-scoped).
* Tags are scanned over the most recent files (capped) so the dropdown stays
* bounded; entity types come from the FileEntityLink distinct set; assignees are
* the tenant's active members.
*/
export async function listFileFilterOptions(input: { tenantId: string }): Promise<FileFilterOptions> {
const TAG_SCAN_LIMIT = 500;
const { tagRows, entityTypeRows } = await withTenantRLS(input.tenantId, async (tx) => {
const tagRows = await tx.file.findMany({
where: { tenantId: input.tenantId },
select: { tags: true },
orderBy: { createdAt: "desc" },
take: TAG_SCAN_LIMIT,
});
const entityTypeRows = await tx.fileEntityLink.findMany({
where: { tenantId: input.tenantId },
select: { entityType: true },
distinct: ["entityType"],
orderBy: { entityType: "asc" },
});
return { tagRows, entityTypeRows };
});
const tags = Array.from(new Set(tagRows.flatMap((row) => row.tags))).sort((a, b) => a.localeCompare(b));
const entityTypes = entityTypeRows.map((row) => row.entityType);
export async function listFileFilterOptions(input: { tenantId: string; ctx: FileVisibilityContext }): Promise<FileFilterOptions> {
if (!input.ctx.permissions.some((permission) => ["files.read_own", "files.read_all"].includes(permission))) {
return { entityTypes: [], tags: [], assignees: [] };
}
const [rows, members] = await Promise.all([
withTenantRLS(input.tenantId, async (tx) => {
const visibility = await fileReadScopeWhereWithTx(tx, input.tenantId, input.ctx);
return loadFileFilterRowsWithTx(tx, input.tenantId, visibility);
}),
canListFileAssignees(input.ctx) ? getTenantUsers(input.tenantId) : Promise.resolve<Awaited<ReturnType<typeof getTenantUsers>>>([]),
]);
return buildFileFilterOptions(rows, members);
}
const members = await getTenantUsers(input.tenantId);
const assignees = members
.map((member) => ({ id: member.user.id, name: fullName(member.user) }))
.sort((a, b) => a.name.localeCompare(b.name));
return { entityTypes, tags, assignees };
/**
* Load browser rows and filter metadata from one visibility snapshot. This
* avoids rebuilding project/file visibility independently for the two queries.
*/
export async function loadFileBrowserData(
input: ListFilesForBrowserInput
): Promise<FileBrowserPage & { filterOptions: FileFilterOptions }> {
const canReadFiles = input.ctx.permissions.some((permission) => ["files.read_own", "files.read_all"].includes(permission));
const [scopedData, members] = await Promise.all([
withTenantRLS(input.tenantId, async (tx) => {
const visibility = await fileReadScopeWhereWithTx(tx, input.tenantId, input.ctx);
const [browser, filterRows] = await Promise.all([
listFilesForBrowserWithTx(tx, input, visibility),
canReadFiles ? loadFileFilterRowsWithTx(tx, input.tenantId, visibility) : Promise.resolve<FileFilterRows>({ tagRows: [], entityTypeRows: [] }),
]);
return { browser, filterRows };
}),
canReadFiles && canListFileAssignees(input.ctx) ? getTenantUsers(input.tenantId) : Promise.resolve<Awaited<ReturnType<typeof getTenantUsers>>>([]),
]);
return {
...scopedData.browser,
filterOptions: buildFileFilterOptions(scopedData.filterRows, members),
};
}
// --- Bulk ZIP -------------------------------------------------------------
/** Max files a single bulk-ZIP may contain (defensive bound for the in-memory zip). */
/** Max files a single bulk-ZIP may contain. */
export const BULK_ZIP_MAX_FILES = 50;
/** Max total original bytes a single bulk-ZIP may pull (in-memory safety). */
/** Max total original bytes a single bulk-ZIP may pull. */
export const BULK_ZIP_MAX_TOTAL_BYTES = 200 * 1024 * 1024;
export const BULK_ZIP_DOWNLOAD_CONCURRENCY = 4;
export const BULK_ZIP_DOWNLOAD_TIMEOUT_MS = 15_000;
export type BulkZipEntry = { name: string; bytes: Uint8Array };
export type BulkZipResult = {
@@ -610,18 +849,51 @@ export type BulkZipResult = {
skippedCount: number;
};
export async function readBulkZipResponseBytes(response: Response, maxBytes: number): Promise<Uint8Array> {
if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
throw new TypeError("Bulk ZIP response limit must be a non-negative safe integer.");
}
const contentLength = response.headers.get("content-length");
if (contentLength && /^\d+$/u.test(contentLength) && Number(contentLength) > maxBytes) {
await response.body?.cancel().catch(() => undefined);
throw new FileServiceError("files.errors.downloadFailed");
}
if (!response.body) {
return new Uint8Array();
}
const reader = response.body.getReader();
const chunks: Uint8Array[] = [];
let totalBytes = 0;
while (true) {
const chunk = await reader.read();
if (chunk.done) break;
totalBytes += chunk.value.byteLength;
if (totalBytes > maxBytes) {
await reader.cancel().catch(() => undefined);
throw new FileServiceError("files.errors.downloadFailed");
}
chunks.push(chunk.value);
}
const bytes = new Uint8Array(totalBytes);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
return bytes;
}
/**
* Collect the byte payloads for a bulk-ZIP download (tenant-scoped, fail-closed).
* Only files that are visible to the user AND scan-clean/skipped are included; an
* Only files that are visible to the user AND scan-clean are included; an
* infected/pending/invisible/over-cap file is silently dropped (never leaked into
* the archive). Bytes are pulled via short-lived signed URLs (AD-23, no public
* bucket). Entry names are de-duplicated so the zip stays valid.
*/
export async function collectFilesForZip(input: {
tenantId: string;
ctx: FileVisibilityContext;
fileIds: readonly string[];
}): Promise<BulkZipResult> {
export async function collectFilesForZip(input: { tenantId: string; ctx: FileVisibilityContext; fileIds: readonly string[] }): Promise<BulkZipResult> {
const ids = Array.from(new Set(input.fileIds)).slice(0, BULK_ZIP_MAX_FILES);
if (ids.length === 0) {
return { entries: [], skippedCount: 0 };
@@ -630,43 +902,59 @@ export async function collectFilesForZip(input: {
const where: Prisma.FileWhereInput = {
tenantId: input.tenantId,
id: { in: ids },
scanStatus: { in: ["clean", "skipped"] },
scanStatus: "clean",
};
if (!hasPermission(input.ctx, "files.read_all")) {
where.OR = [
{ createdByUserId: input.ctx.userId },
{ assignedToUserId: input.ctx.userId },
{ links: { some: { tenantId: input.tenantId } } },
];
}
const files = await withTenantRLS(input.tenantId, async (tx) => {
Object.assign(where, await fileReadScopeWhereWithTx(tx, input.tenantId, input.ctx, ids));
return tx.file.findMany({ where, select: { id: true, displayName: true, storageKey: true, sizeBytes: true } });
});
const files = await withTenantRLS(input.tenantId, (tx) =>
tx.file.findMany({ where, select: { id: true, displayName: true, storageKey: true, sizeBytes: true } }),
);
const usedNames = new Set<string>();
const entries: BulkZipEntry[] = [];
let totalBytes = 0;
const candidates: typeof files = [];
let reservedBytes = 0;
let skippedCount = ids.length - files.length;
for (const file of files) {
if (!file.storageKey || totalBytes + file.sizeBytes > BULK_ZIP_MAX_TOTAL_BYTES) {
if (!file.storageKey || file.sizeBytes < 0 || reservedBytes + file.sizeBytes > BULK_ZIP_MAX_TOTAL_BYTES) {
skippedCount += 1;
continue;
}
try {
const url = await createMediaDownloadUrl({ key: file.storageKey });
const response = await fetch(url);
if (!response.ok) {
skippedCount += 1;
continue;
}
const bytes = new Uint8Array(await response.arrayBuffer());
totalBytes += bytes.byteLength;
entries.push({ name: uniqueZipName(file.displayName, usedNames), bytes });
} catch {
reservedBytes += file.sizeBytes;
candidates.push(file);
}
const downloaded: Array<{ file: (typeof files)[number]; bytes: Uint8Array } | null> = [];
for (let offset = 0; offset < candidates.length; offset += BULK_ZIP_DOWNLOAD_CONCURRENCY) {
const batch = candidates.slice(offset, offset + BULK_ZIP_DOWNLOAD_CONCURRENCY);
downloaded.push(
...(await Promise.all(
batch.map(async (file) => {
try {
const url = await createMediaDownloadUrl({ key: file.storageKey! });
const response = await fetch(url, {
redirect: "error",
signal: AbortSignal.timeout(BULK_ZIP_DOWNLOAD_TIMEOUT_MS),
});
if (!response.ok) {
await response.body?.cancel().catch(() => undefined);
return null;
}
return { file, bytes: await readBulkZipResponseBytes(response, file.sizeBytes) };
} catch {
return null;
}
})
))
);
}
const usedNames = new Set<string>();
const entries: BulkZipEntry[] = [];
for (const result of downloaded) {
if (!result) {
skippedCount += 1;
continue;
}
entries.push({ name: uniqueZipName(result.file.displayName, usedNames), bytes: result.bytes });
}
return { entries, skippedCount };
@@ -701,14 +989,12 @@ export async function linkFile(input: {
entityType: FileEntityType;
entityId: string;
linkRole?: string | null;
ctx: FileVisibilityContext;
}): Promise<void> {
await withTenantRLS(input.tenantId, async (tx) => {
// Ensure the file belongs to the tenant before linking.
const file = await tx.file.findFirst({ where: { id: input.fileId, tenantId: input.tenantId }, select: { id: true } });
if (!file) {
throw new CatalogError(foundationErrors.notFound, { fileId: input.fileId });
}
await tx.fileEntityLink.upsert({
await getVisibleFileOrThrowWithTx(tx, input.tenantId, input.fileId, input.ctx);
await assertFileLinkTargetVisibleWithTx(tx, input.tenantId, input.entityType, input.entityId, input.ctx);
const link = await tx.fileEntityLink.upsert({
where: { fileId_entityType_entityId: { fileId: input.fileId, entityType: input.entityType, entityId: input.entityId } },
update: { linkRole: input.linkRole ?? null },
create: {
@@ -719,16 +1005,51 @@ export async function linkFile(input: {
entityId: input.entityId,
linkRole: input.linkRole ?? null,
},
select: { id: true, createdAt: true },
});
if (input.entityType === "project") {
const readyInternalFile = await tx.file.findFirst({
where: {
id: input.fileId,
tenantId: input.tenantId,
archivedAt: null,
scanStatus: "clean",
createdByPortalUserId: null,
source: { not: "customer_portal" },
},
select: { id: true },
});
if (readyInternalFile) {
await publishOutboxEvent(
tx as unknown as OutboxPublisherTransaction,
buildPortalDocumentReadyOutboxEvent({
tenantId: input.tenantId,
projectId: input.entityId,
fileId: input.fileId,
fileEntityLinkId: link.id,
linkVersion: link.createdAt,
userId: input.userId,
})
);
}
}
});
}
export async function unlinkFile(input: { tenantId: string; fileId: string; entityType: FileEntityType; entityId: string }): Promise<void> {
await withTenantRLS(input.tenantId, (tx) =>
tx.fileEntityLink.deleteMany({
export async function unlinkFile(input: {
tenantId: string;
fileId: string;
entityType: FileEntityType;
entityId: string;
ctx: FileVisibilityContext;
}): Promise<void> {
await withTenantRLS(input.tenantId, async (tx) => {
await getVisibleFileOrThrowWithTx(tx, input.tenantId, input.fileId, input.ctx);
await assertFileLinkTargetVisibleWithTx(tx, input.tenantId, input.entityType, input.entityId, input.ctx);
await tx.fileEntityLink.deleteMany({
where: { tenantId: input.tenantId, fileId: input.fileId, entityType: input.entityType, entityId: input.entityId },
}),
);
});
});
}
export async function archiveFile(input: { tenantId: string; fileId: string }): Promise<void> {
@@ -783,7 +1104,7 @@ export async function regenerateFilePreview(input: { tenantId: string; fileId: s
const file = await withTenantRLS(input.tenantId, async (tx) => {
const row = await tx.file.findFirst({
where: { id: input.fileId, tenantId: input.tenantId },
select: { id: true, storageKey: true, mimeType: true, previewStatus: true },
select: { id: true, storageKey: true, mimeType: true, previewStatus: true, scanStatus: true },
});
if (!row) {
throw new CatalogError(foundationErrors.notFound, { fileId: input.fileId });
@@ -791,12 +1112,25 @@ export async function regenerateFilePreview(input: { tenantId: string; fileId: s
if (row.previewStatus !== "failed") {
throw new FileServiceError("files.error.previewNotRegenerable");
}
if (row.scanStatus !== "clean") {
throw new FileServiceError("files.error.previewNotRegenerable");
}
await tx.file.update({ where: { id: row.id }, data: { previewStatus: "pending" } });
return row;
});
const bucket = resolveStorageBucket();
// Enqueue stays OUTSIDE the RLS transaction.
await enqueueFilePreview({ fileId: file.id, tenantId: input.tenantId, bucket, storageKey: file.storageKey, mimeType: file.mimeType }).catch(() => {});
try {
const result = await enqueueFilePreview({ fileId: file.id, tenantId: input.tenantId, bucket, storageKey: file.storageKey, mimeType: file.mimeType });
if (!result.enqueued) {
throw new Error("File preview queue is unavailable");
}
} catch {
await withTenantRLS(input.tenantId, (tx) =>
tx.file.updateMany({ where: { id: file.id, tenantId: input.tenantId, previewStatus: "pending" }, data: { previewStatus: "failed" } })
).catch(() => {});
throw new FileServiceError("files.error.previewNotRegenerable");
}
}
export async function hardDeleteFile(input: { tenantId: string; fileId: string }): Promise<void> {
@@ -804,7 +1138,7 @@ export async function hardDeleteFile(input: { tenantId: string; fileId: string }
tx.file.findFirst({
where: { id: input.fileId, tenantId: input.tenantId },
select: { id: true, storageKey: true, previewStorageKey: true, thumbnailStorageKey: true },
}),
})
);
if (!file) {
throw new CatalogError(foundationErrors.notFound, { fileId: input.fileId });
@@ -813,7 +1147,11 @@ export async function hardDeleteFile(input: { tenantId: string; fileId: string }
// S3 deletes stay OUTSIDE the RLS transaction.
for (const key of [file.storageKey, file.previewStorageKey, file.thumbnailStorageKey]) {
if (key) {
await deleteFile({ bucket, key }).catch(() => {});
// Keep the database row (and therefore the tenant's quota accounting)
// until every durable object has been removed. S3 deletes are
// idempotent, so a failed request can safely be retried without leaving
// an untracked, still-billable object behind.
await deleteFile({ bucket, key });
}
}
// FileEntityLink rows cascade on File delete (schema onDelete: Cascade).