// P4 Files (AK-P4a) §2 — storage path convention (Hetzner, private). // // Tenant isolation is TWOFOLD: // (a) every key carries the prefix `tenants/{tenantId}/` (hard-checked by // authorizeStorageObjectAccess); // (b) the app calls assertFileKeyBelongsToTenant() before every storage // access, so a foreign tenant's key is never resolved. // // Pure functions, no I/O — testable without storage. The bucket itself comes // from STORAGE_BUCKET (staging: hivegrid-staging-media), NOT from these keys. import { authorizeStorageObjectAccess, type StorageAccessOperation } from "../access/index.js"; export type FilePreviewExtension = "png" | "webp" | "jpg"; export interface FileStorageKeys { /** Original-Objekt: tenants/{tenantId}/files/{fileId}/original */ readonly original: string; /** Thumbnail (immer WebP): tenants/{tenantId}/files/{fileId}/thumb.webp */ readonly thumbnail: string; } function requireSegment(value: string, field: string): string { const normalized = value.trim(); if (normalized.length === 0 || normalized.includes("/") || normalized.includes("\\")) { throw new Error(`Invalid storage path segment for ${field}: must be a non-empty id without slashes.`); } return normalized; } /** Base prefix of a file. */ export function fileStoragePrefix(tenantId: string, fileId: string): string { return `tenants/${requireSegment(tenantId, "tenantId")}/files/${requireSegment(fileId, "fileId")}`; } /** Original and thumbnail key of a file. */ export function buildFileStorageKeys(tenantId: string, fileId: string): FileStorageKeys { const prefix = fileStoragePrefix(tenantId, fileId); return { original: `${prefix}/original`, thumbnail: `${prefix}/thumb.webp`, }; } /** Preview key with a format-dependent extension (PDF->png, image->webp, HEIC->jpg). */ export function buildFilePreviewKey(tenantId: string, fileId: string, extension: FilePreviewExtension): string { return `${fileStoragePrefix(tenantId, fileId)}/preview.${extension}`; } /** Temp key of an upload chunk: tenants/{tenantId}/uploads/{uploadId}/chunk-{index}. */ export function buildUploadChunkKey(tenantId: string, uploadId: string, chunkIndex: number): string { if (!Number.isInteger(chunkIndex) || chunkIndex < 0) { throw new Error(`Invalid chunk index: ${chunkIndex}`); } return `tenants/${requireSegment(tenantId, "tenantId")}/uploads/${requireSegment(uploadId, "uploadId")}/chunk-${chunkIndex}`; } /** Prefix of all temp chunks of an upload session (for cleanup). */ export function uploadChunkPrefix(tenantId: string, uploadId: string): string { return `tenants/${requireSegment(tenantId, "tenantId")}/uploads/${requireSegment(uploadId, "uploadId")}`; } /** * Throws if `key` does not belong to `tenantId`. Thin wrapper around * authorizeStorageObjectAccess (single source of truth for the * `tenants/{tenantId}/` prefix + path-traversal guard). Call BEFORE every * download/delete of a key read from the DB. */ export function assertFileKeyBelongsToTenant( tenantId: string, key: string, operation: StorageAccessOperation = "download", ): string { const decision = authorizeStorageObjectAccess({ tenantId, key, operation }); if (!decision.allowed) { throw new Error(`Storage key does not belong to tenant (${decision.reason}).`); } return decision.key; }