Track HiveGrid Cloud planning reference
This commit is contained in:
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;
|
||||
}
|
||||
Reference in new issue
Block a user