Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,79 @@
// 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;
}