@lilaquadrat/studio 9.20.2 → 10.0.0-beta.1

package/lib/cjs/src/services/storage.service.d.ts

@@ -0,0 +1,192 @@
+/// <reference types="node" />
+import { ObjectId } from 'mongodb';
+import { Media, ListOfModels, MediaStats, Options, Upload, Stored, UserAppOptionsRequired, MediaMetadata, Storage, StorageFilePaths } from '@lilaquadrat/interfaces';
+import { type MultipartFile } from '@fastify/multipart';
+import Immutable from '../Immutable.class';
+export declare class StorageService extends Immutable<Storage> {
+    buckets: {
+        cdn: {
+            public: boolean;
+            overwrite: boolean;
+            cache: number;
+        };
+        hosting: {
+            public: boolean;
+            overwrite: boolean;
+            cache: number;
+        };
+        secure: {
+            public: boolean;
+            overwrite: boolean;
+            cache: number;
+        };
+        internal: {
+            public: boolean;
+            overwrite: boolean;
+            cache: number;
+        };
+    };
+    model: import("../classes/modelv2.class").default<Storage, string>;
+    options: {
+        dataFolder: string;
+        uploadFolder: string;
+    };
+    constructor(options: {
+        dataFolder: string;
+        uploadFolder: string;
+    });
+    /**
+     * Generates a secure, time-limited token for accessing files in secure storage buckets.
+     *
+     * The token is cryptographically signed using HMAC-SHA256 and base64url-encoded to be
+     * non-human readable and URL-safe.
+     *
+     * @param fileId - The file identifier (ObjectId or string) to grant access to
+     * @param expiresIn - Time in seconds until the token expires (default: 3600 = 1 hour)
+     * @param limits - Optional restrictions to apply to the token
+     * @param limits.company - Restrict token to specific company
+     * @param limits.project - Restrict token to specific project
+     * @param limits.app - Restrict token to specific app
+     * @param limits.url - Restrict token to specific URL path prefix
+     * @param limits.prefix - Restrict token to specific file prefix
+     *
+     * @returns Base64url-encoded token containing: fileId:expires[:limits]:signature
+     *
+     * @example
+     * // Generate token valid for 1 hour with no restrictions
+     * const { token } = getSecureToken('507f1f77bcf86cd799439011', 3600);
+     *
+     * @example
+     * // Generate token limited to specific company and project
+     * const { token } = getSecureToken('507f1f77bcf86cd799439011', 3600, {
+     *   company: 'acme',
+     *   project: 'website'
+     * });
+     *
+     * @example
+     * // Generate token limited to specific URL path
+     * const { token } = getSecureToken('507f1f77bcf86cd799439011', 3600, {
+     *   url: '/company/project/files/'
+     * });
+     */
+    getSecureToken(fileId: string | ObjectId, expiresIn?: number, limits?: {
+        company?: string;
+        project?: string;
+        app?: string;
+        url?: string;
+        prefix?: string;
+    }): {
+        token: string;
+        expiresIn: number;
+        createdAt: number;
+        expiresAt: number;
+    };
+    /**
+     * Validates a secure token and optionally checks if it matches provided limits.
+     *
+     * Performs validations:
+     * 1. Signature verification using HMAC-SHA256
+     * 2. Expiration timestamp check
+     * 3. Optional limit validation against provided check values
+     *
+     * @param token - The base64url-encoded token to validate
+     * @param checkLimits - Optional values to verify against token's restrictions
+     * @param checkLimits.company - Company to check against token limit
+     * @param checkLimits.project - Project to check against token limit
+     * @param checkLimits.app - App to check against token limit
+     * @param checkLimits.url - URL path to check against token limit
+     * @param checkLimits.prefix - File prefix to check against token limit
+     *
+     * @returns true if token is valid and all checks pass, false otherwise
+     *
+     * @example
+     * // Validate token without checking limits
+     * const isValid = validateSecureToken(token);
+     *
+     * @example
+     * // Validate token and check company/project access
+     * const isValid = validateSecureToken(token, {
+     *   company: 'acme',
+     *   project: 'website'
+     * });
+     */
+    validateSecureToken(token: string, checkLimits?: {
+        company?: string;
+        project?: string;
+        app?: string;
+        url?: string;
+        prefix?: string;
+    }): boolean;
+    /**
+     * Creates a secure download URL with time-limited token for a storage file.
+     *
+     * @param fileId - The ObjectId of the storage document
+     * @param options - Required options containing company, project
+     * @param expiresIn - Time in seconds until the token expires (default: 3600 = 1 hour)
+     * @param limits - Optional additional restrictions for the token
+     *
+     * @returns Object containing the full download URL with token and expiration timestamp
+     *
+     * @example
+     * const download = await createSecureDownload(
+     *   new ObjectId('507f1f77bcf86cd799439011'),
+     *   { company: 'acme', project: 'website' },
+     *   3600
+     * );
+     * // Returns: { url: 'https://...?token=...', expiresAt: 1234567890 }
+     */
+    createSecureDownload(fileId: ObjectId, options: Required<Options>, expiresIn?: number, limits?: {
+        company?: string;
+        project?: string;
+        app?: string;
+        url?: string;
+        prefix?: string;
+    }): Promise<{
+        url: string;
+        expiresAt: number;
+    }>;
+    handleFile(uploadInternalId: ObjectId, index: number, file: MultipartFile | undefined): Promise<Stored<Upload>>;
+    complete(upload: Upload, options?: {
+        useNode?: boolean;
+    }): Promise<StorageFilePaths>;
+    writeFile(data: MultipartFile['file'] | Upload['paths'], index: number | undefined, internalId: ObjectId, type: 'upload' | 'file', options?: {
+        useNode?: boolean;
+    }): Promise<StorageFilePaths>;
+    writeFileVersion(data: Buffer, internalId: ObjectId, version: string): Promise<StorageFilePaths>;
+    private concatenateFiles;
+    private concatenateFilesWithCat;
+    removeUploadFiles(upload: Upload): Promise<void>;
+    removeLocalFile(relativePath: string): Promise<void>;
+    /**
+     * creata directory structure for the given file
+     * e.g. ``/b1/f1/68fb87d6db4fb20117bcd3ce.000001``
+     */
+    fanoutPath(uploadId: string, version?: string): StorageFilePaths;
+    uploadPath(uploadId: string, index: number): StorageFilePaths;
+    static sanitizeName(name: string): string;
+    getMetadata(upload: Upload, metadata?: MediaMetadata): MediaMetadata;
+    get(company: string, project?: string, app?: string, query?: any, limit?: {
+        skip: number;
+        limit: number;
+    }): Promise<ListOfModels<Media>>;
+    getTags(company: string, project: string, search: string): Promise<string[]>;
+    single(company: string, project: string, filename: string): Promise<Media | null>;
+    content(company: string, project: string, id: ObjectId): Promise<Media | null>;
+    /**
+     * checks if the file was already successfully uploaded
+     */
+    exists(filename: string, prefix: string | undefined, app: string, options: {
+        company: string;
+        project: string | undefined;
+    }): Promise<boolean>;
+    matchSortTags(documents: any[], search: RegExp | string, sort: string): string[];
+    checkAllowedSize(filesize: number, allowedSize: number): boolean;
+    stats(company: string, project: string): Promise<MediaStats>;
+    getByInternalId(internalId: ObjectId, options: Required<Options>): Promise<import("mongodb").WithId<Storage> | null>;
+    getPathByFilename(filename: string, app: string, options: Required<Options>): Promise<import("mongodb").WithId<Storage> | null>;
+    getByFilename(filename: string, prefix: string | undefined, bucket: string, options: Required<Options>): Promise<import("mongodb").WithId<Storage> | null>;
+    removeBlob(internalId: ObjectId, options: Required<UserAppOptionsRequired>): Promise<import("mongodb").DeleteResult>;
+    removeBlobVersion(parentId: ObjectId, options: Required<UserAppOptionsRequired>): Promise<void>;
+}
+declare const _default: StorageService;
+export default _default;