80 lines
3.3 KiB
TypeScript
80 lines
3.3 KiB
TypeScript
// 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;
|
|
}
|